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Preface 


Intended Audience 

All users of the VMS operating system can benefit from using command 
procedures. You can write command procedures to perform either simple 
tasks or complex tasks that approximate the capabilities of a high-level 
programming language. 

This manual presents key concepts and techniques for developing command 
procedures using the VMS DIGITAL Command Language (DCL). Many 
examples, including examples of complete command procedures, are intended 
to demonstrate applications of the concepts and techniques discussed. The 
examples included in this document include elementary, advanced, and 
complex command procedures. 


Document Structure 

This guide contains eight chapters and three appendixes: 

• Chapter 1 is an introduction to using and developing command 
procedures. 

• Chapter 2 describes some of the DCL concepts that you use when 
developing command procedures. 

• Chapter 3 discusses sending input to and receiving output from command 
procedures. 

• Chapter 4 discusses the use of lexical functions in command procedures. 

• Chapter 5 discusses concepts used in designing a command procedure 

and describes techniques for controlling execution flow in a command 
procedure. 

• Chapter 6 describes how to access files for input and output in a 
command procedure. 

• Chapter 7 describes error handling within command procedures. 

• Chapter 8 describes how to use command procedures in batch processes. 

• Appendix A contains eleven annotated sample command procedures. 

• Appendix B is a summary of lexical functions. 

• Appendix C lists DCL commands that are frequently used in command 
procedures. 


xiii 
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Associated Documents 

The following documents contain information related to this guide: 

• Introduction to VMS contains general information about using the VMS 
operating system. 

• VMS DCL Concepts Manual describes the DIGITAL Command Language 
(DCL), defines the format and use of file specifications, and (of particular 
interest to those writing command procedures) contains many examples 
of specific DCL commands. 

• VMS DCL Dictionary contains complete descriptions of all DCL 
commands. 


Conventions 



Convention Meaning 


[ret] 


CTRL/C 


$ SHOW TIME 
05-JUN-1988 11:55:22 

$ TYPE MYFILE.DAT 


input-file, . . . 


In examples, a key name (usually abbreviated) 
shown within a box indicates that you press 
a key on the keyboard; in text, a key name is 
not enclosed in a box. In this example, the key 
is the RETURN key. (Note that the RETURN 
key is not usually shown in syntax statements 
or in all examples; however, assume that you 
must press the RETURN key after entering a 
command or responding to a prompt.) 

A key combination, shown in uppercase with a 
slash separating two key names, indicates that 
you hold down the first key while you press the 
second key. For example, the key combination 
CTRL/C indicates that you hold down the key 
labeled CTRL while you press the key labeled C. 
In examples, a key combination is enclosed in a 
box. 

In examples, system output (what the system 
displays) is shown in black. User input (what 
you enter) is shown in red. 

In examples, a vertical series of periods, or 
ellipsis, means either that not all the data that 
the system would display in response to a 
command is shown or that not all the data a 
user would enter is shown. 

In examples, a horizontal ellipsis indicates 
that additional parameters, values, or other 
information can be entered, that preceding 
items can be repeated one or more times, or 
that optional arguments in a statement have 
been omitted. 
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Convention 

Meaning 

[logical-name] 

Brackets indicate that the enclosed item is 
optional. (Brackets are not, however, optional 
in the syntax of a directory name in a file 
specification or in the syntax of a substring 
specification in an assignment statement.) 

quotation marks 
apostrophes 

The term quotation marks is used to refer 
to double quotation marks ("). The term 
apostrophe (') is used to refer to a single 
quotation mark. 
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New and Changed Features 


The following additions have been made to this manual since it was produced 
at Version 4.0: 












Chapter 1 contains instructions for using the TYPE command to execute 
command procedures located on remote nodes. 

Chapter 2 contains instructions for using the SET SYMBOL command to 
mask global or local symbols in a command procedure. 

Chapter 4 describes the F$GETQUI lexical function and includes an 
example illustrating how to use this lexical function. 

Chapter 5 describes the enhanced IF language construct. The IF language 
construct now allows you to specify a block of commands following the 
THEN command, and supports a new ELSE command. This chapter 
also describes the CALL command, which transfers control to a labeled 
subroutine and creates a new procedure level. 

Chapter 8 contains information about the new SET ENTRY and SHOW 
ENTRY commands, which allow you to display information about a batch 
job and change the characteristics of a batch job. 

Appendix A contains a new example command procedure called 
COMPILE_JILE.COM. This command procedure illustrates the use 
of the enhanced IF language construct. 
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Developing Command Procedures 


A command procedure is a file that contains DCL commands and data lines 
used by DCL commands. You can write command procedures to execute 
simple tasks or complex tasks that approximate the capabilities of a high-level 
programming language. When you execute a command procedure, the DCL 
command interpreter reads the file and executes the commands it contains. 

This manual describes how to design and write command procedures. It 
explains tasks such as obtaining input, writing output, establishing loops, 
and designing error-checking routines, as well as the DCL concepts you must 
understand to write command procedures. This manual also describes how to 
execute command procedures interactively and in batch mode. 

A simple command procedure can contain a sequence of commands that you 
use frequently. For example, you might enter the DIRECTORY command 
each time you set default to the subdirectory where you keep your work files. 
You can use the following command procedure, called GO_DIR.COM, to set 
default to the work directory, called [PERRY.ACCOUNTS], and display a list 
of files in that directory. 

$ SET DEFAULT [PERRY.ACCOUNTS] 

$ DIRECTORY 
$ EXIT 

Enter the following command to execute GO_DIR.COM: 

$ QGO.DIR 

This command tells the DCL command interpreter to read the file GO_ 
DIR.COM and to execute the commands in the file. Therefore, the command 
interpreter sets your default directory to [PERRY.ACCOUNTS] and issues 
the DIRECTORY command. The system displays the output from the 
DIRECTORY command on your terminal. 

You can revise GO_DIR.COM to allow you to set default to any directory 
and obtain a list of the files in the directory: 

$ INQUIRE DIR.NAME "Directory name" 

$ SET DEFAULT ’DIR.NAME’ 

$ DIRECTORY 
$ EXIT 

When you execute this version of GO_DIR.COM, the INQUIRE command 
prompts for a directory name, the SET DEFAULT command moves you 
to that directory, and the system displays the output of the DIRECTORY 
command on your terminal. 
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Developing Command Procedures 

1.1 Formatting Command Procedures 


1.1 Formatting Command Procedures 

Use a text editor (or the DCL command CREATE) to create and format a 
command procedure. When you name the command procedure, use the 
file type COM. Both the @ command, which is used to execute command 
procedures interactively, and the SUBMIT command, which is used to execute 
command procedures in batch mode, append the default file type COM to the 
file name you specify. If you use another file type, you must specify the file 
type when you execute the command procedure. 

Command procedures contain DCL commands that you want the DCL 
command interpreter to execute and data lines that are used by these 
commands. Commands must begin with a dollar sign. You can start the 
command immediately after the dollar sign, or you can place one or more 
spaces or tabs before the command to make the command procedure easier to 
read. 

Data lines, unlike commands, usually do not begin with a dollar sign. Data 
lines are used as input data for commands or programs. Data lines are used 
by the most recently issued command; the DCL command interpreter does 
not process data lines. 

Note: If you need to begin a data line with a dollar sign, use the DECK and 
EOD commands. See Chapter 3 for more information. 

The following example illustrates command lines and data lines in a 
command procedure. 

$ MAIL 
SEND 
THOMAS 
MY MEMO 

Do you have a few minutes to talk about the 
ideas I presented in my memo? 

$ ! 

$ SHOW USERS THOMAS 
$ EXIT 

The first line is a command and must therefore start with a dollar sign. The 
next lines are data lines that are used by the Mail Utility; these lines must not 
start with dollar signs. Note that the data lines correspond to the way that the 
image (invoked by the command) expects the data. Therefore, the data lines 
provide a MAIL command (SEND), a recipient (THOMAS), a subject (MY 
MEMO) and the text of the mail message. When the command interpreter 
finds a new line that begins with a dollar sign, the Mail Utility is terminated. 

Use the following formatting conventions to make your command procedures 
easier to read and maintain: 

• Use comments to document your command procedures. 

• If a command is very long or includes many qualifiers, continue it on 
more than one line. Terminate the first line of the command string with a 
hyphen character; do not start a continuation line with a dollar sign. 

• Use complete command names and qualifier names. 

• Use labels to identify related groups of commands and use indentation to 
make loops and conditional coding easier to understand. 

These formatting conventions are described in the following sections. 
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Developing Command Procedures 

1.1 Formatting Command Procedures 


1.1.1 Documenting Command Procedures 

It is good programming practice to document your command procedures 
so they are easy to read and to maintain. At the beginning of a command 
procedure, use comments to describe the procedure and any parameters 
that are passed to it. Also, use comments at the beginning of each block of 
commands to describe that section of the procedure. 

The exclamation point (!) begins a comment in command procedures. DCL 
considers everything to the right of an exclamation point to be a comment 
and ignores this information when processing the line. 

The following example uses comments to document a command procedure 
and to make it easier to read. 

$! This procedure sends mail to THOMAS and 
$! asks him if he has time to talk 
$! 

$! 

$ MAIL 
SEND 
THOMAS 
MY MEMO 

Do you have a few minutes to talk about the 
ideas I presented in my memo? 

$! 

$ EXIT 

Note that whenever you insert a blank line in a command procedure, 
you must start the line with a dollar sign. If you omit the dollar sign, 

DCL interprets the line as data and issues a warning message. Also, you 
should include an exclamation point after the dollar sign. Although not 
required, the exclamation point helps the procedure run faster because the 
command interpreter ignores the line as a comment rather than searching for 
a command. 

If you must use an exclamation point character as part of the text in a 
command line, enclose it in quotation marks so the command interpreter will 
not interpret the exclamation point as a comment delimiter. If you use an 
exclamation point character in a data line, the image to which you pass the 
data processes the exclamation point. 


1.1.2 Using Multiple Lines for a Single Command 

If you are writing a command that includes many qualifiers, you can make 
the command procedure more readable by listing the qualifiers on separate 
lines rather than running them together. To do this, use the hyphen as a 
continuation character, just as you do for interactive command continuation. 
Do not begin the continued line with a dollar sign. For example: 

$ PRINT TEST.OUT - 

/AFTER=18:00 - 
/C0PIES=10 - 
/QUEUE=LPB0: 

The spaces preceding each qualifier are not required, but they make the 
command string more readable. 
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Developing Command Procedures 

1.1 Formatting Command Procedures 


1.1.3 Using Complete Command Names and Qualifier Names 

Even though DCL syntax rules allow truncation, you should use complete 
command, qualifier, and keyword names in command procedures. This helps 
to document the command procedure, because DCL commands and qualifiers 
are generally named according to the functions they perform. For example, 
compare the following two lines: 

$ PRINT ALPHA.LIS/C0PIES=2 
$ PR ALPHA/C=2 

The first command line expresses clearly the request to print two copies of the 
file ALPHA.LIS. The second line is terse and may not be easily interpreted by 
other users (or remembered by yourself). 

If you use abbreviations in command procedures, these abbreviations may not 
uniquely identify commands in a future release of the VMS operating system. 


1.1.4 Using Labels 

In longer command procedures, you can improve readability by using 
labels to identify related groups of commands. A label can have up to 
255 characters, cannot contain embedded blanks, and must be terminated by 
a colon. When labels mark the start of a loop, use spaces or tabs to indent 
the commands in the body of the loop. (A loop is a group of commands that 
executes repeatedly until a condition is met.) When you indent commands, 
the dollar sign should still be in column 1. For example: 

$! This procedure modifies the fifth 
$! record in the file EMPLOYEES.DAT 
$! 

$ OPEN/READ/WRITE IN.FILE EMPLOYEES.DAT 
$ COUNT = 1 
$ FIND.RECORD: 

$ IF COUNT .GT. 5 THEN GOTO REVISE 

$ READ IN.FILE RECORD 

$ COUNT = COUNT + 1 

$ GOTO FIND.RECORD 

$! 

$ REVISE: 


In this example, the label FIND_RECORD begins the loop used to search for 
the fifth record in the file. The commands in the loop are indented, making 
the body of the loop easier to read. 

The commands IF and GOTO, and techniques for constructing loops in 
command procedures, are described in Chapter 5. 
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1.2 Executing Command Procedures 

You can execute command procedures in two modes: interactive and batch. 

In interactive mode, the commands within a command procedure execute 
as if you were entering them from your terminal. You cannot execute any 
other commands from your terminal until the procedure terminates. In batch 
mode, the system creates a separate process to run the command procedure. 
After you submit a batch job, you can continue to use your terminal while the 
batch job executes. 

You can also use the TYPE command to execute a command procedure on a 
remote node. 


1.2.1 Executing Command Procedures Interactively 

To execute a command procedure interactively, enter the @ character (execute 
procedure command) followed by the file specification of the procedure. If 
you do not enter a complete file specification, the command interpreter uses 
your current disk and directory and a default file type of COM. For example, 
the following command executes the command procedure WEATHER.COM, 
which is located in your current default directory: 

$ OWEATHER 

When you enter the @ command, the command interpreter executes the 
commands in the file WEATHER.COM. Each command in WEATHER.COM 
executes sequentially. The command interpreter issues the DCL prompt 
at your terminal when WEATHER.COM finishes executing. You can then 
resume interactive work. 

If a command procedure is not in your default directory or does not have the 
file type COM, give the complete file specification, as shown in the following 
example: 

$ SDISK2:[COMMON]SETUP 

For command procedures that you execute frequently, you can define a 
symbol name as a synonym for the entire command line. For example: 

$ SETUP = "QDISK2:[COMMON]SETUP" 

Whenever you want to run DISK2:[COMMON]SETUP.COM, you can use the 
symbol SETUP as if it were a command: 

$ SETUP 

The command interpreter replaces the symbol SETUP with its value 
(@DISK2:[COMMON]SETUP.COM) and then executes the procedure. 
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1.2 Executing Command Procedures 


1.2.2 Submitting Command Procedures for Batch Execution 

If you create and use procedures that require lengthy processing time—for 
example, the compilation or assembly of large source programs—submit these 
procedures as batch jobs. You can use your terminal to perform other tasks 
while the batch job executes. 

Use the SUBMIT command to execute a command procedure as a batch job. 
The SUBMIT command assumes your current disk and directory defaults 
and a default file type of COM for the command procedure. For example, to 
submit the command procedure WEATHER.COM (in your default directory) 
for batch execution, enter the following command: 

$ SUBMIT WEATHER 

Job WEATHER (queue SYSSBATCH, entry 210) started on SYSSBATCH 

$ 

In this example, the system displays a message showing that the job has 
been queued; the message gives you the job number (210) and the name of 
the system queue on which the job is entered (SYS$BATCH). Then the DCL 
prompt is displayed, and you can continue using the terminal. 

Your job stays in the queue until the system is ready to run the job. Then the 
system creates another process for you using your account and your process 
characteristics. The system runs the job from that process and deletes the 
process when the job is completed. For more information on batch jobs, see 
Chapter 8. 


1.2.3 Executing Command Procedures on a Remote Node 

You can use the TYPE command to execute a command procedure 
interactively on any remote node. The output of the command procedure 
is displayed on the user's terminal at the local node. For example, the TYPE 
command lets you execute command procedures to list the users logged on 
to the remote node, or to display the status of services in the local cluster not 
provided clusterwide. A sample command procedure follows: 

$ ! SHOWUSERS.COM 

$ IF F$M0DE() .EQS. "NETWORK" THEN DEFINE/USER SYS$0UTPUT SYSSNET 
$ SHOW USERS 

This command procedure can be used with the TYPE command to display at 
the user's local node a list of users logged on to the remote node on which 
the command procedure resides. 

To execute a command procedure in the default DECnet account of the 
remote node, specify the command procedure as a parameter to the TYPE 
command as follows: 

$ TYPE node_name::"TASK=command_procedure" 

The variable node—name is the name of the remote node on which the 
command procedure resides. The variable command—procedure is the name of 
the command procedure. 

To execute a command procedure in the SYS$LOGIN directory (the top-level 
directory) of another account on the remote node, use an access control string 
in the command, as follows: 
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$ TYPE node_name"user_name password"::"TASK=command_procedure" 

The variable user—name is the user name of the account on the remote node, 
password is the password of the account on the remote node, and command- 
procedure is the name of the command procedure. 

The following command executes the command procedure 
SHOWUSERS.COM and displays the output from this command procedure 
on the user's terminal. The command procedure resides in the SYS$LOGIN 
directory of account BIRD on node ORIOLE. 

$ TYPE ORIOLE"BIRD FLIESFAST"::"TASK=SHOWUSERS" 


VAX/VMS Interactive Users 
09-DEC-1988 17:20:13.30 
Total number of interactive users 


Username Process Name PID 

FLICKER Freddie 00536278 

ROBIN Red 00892674 

DOVE Whitie 00847326 

DUCK Donna 02643859 


5 

Terminal 
TXA1: 
VTA2: 
TXA3: 
RTA1: 


Changing Command Levels 

A command level is an input stream for the DCL command interpreter. When 
you log in and enter commands at your terminal, you are entering commands 
from command level zero. A simple interactive command procedure executes 
at command level 1. When the procedure terminates and the DCL prompt 
reappears on your screen, you are back at command level zero. 


There are two ways to create a new command level within a complex 
command procedure. You can use the CALL command to call a subroutine 
that exists within the command procedure or you can nest command 
procedures by using an execute procedure (@) command inside one 
procedure to execute another procedure. When you use the CALL command 
or nest a command procedure, you increase the command level by one. 

The maximum number of command levels you can achieve with the CALL 
command or by nesting command procedures is 32. 

The following example command procedure creates the indicated command 
levels when you execute it interactively. 


o 
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$ ! Example of command procedure levels 
$ WRITE SYSSOUTPUT "This is an example" O 

$ ^EXAMPLE © 

$ DEFINE FRIEND CAROL © 

$ ON WARNING THEN EXIT 

$ CALL SUB1 © 

$ DEASSIGN FRIEND 
$ EXIT 
$ SUB1: 

$ SUBROUTINE 


© 

© 


© 


$ CALL SUB2 
$ EXIT 

$ ENDSUBROUTINE 
$ SUB2: 

$ SUBROUTINE 


© 


© 


$ EXIT 


o 


$ ENDSUBROUTINE 
$ EXIT 

© The command procedure begins executing at command level 1. 

© The nested command procedure EXAMPLE.COM executes at command 
level 2. 

© After EXAMPLE.COM finishes executing, the DEFINE command executes 
at command level 1. 

© The CALL SUB1 command creates a new command level; subroutine 
SUB1 executes at command level 2. 

© The CALL SUB2 command within subroutine SUB1 creates a new 
command level. Subroutine SUB2 executes at command level 3. 

© The EXIT command within SUB1 returns control to the DEASSIGN 
command following the CALL SUB1 command. The DEASSIGN 
command executes at command level 1. 

© The EXIT command within SUB2 returns control to subroutine SUB1, that 
is executing at command level 2. Note that this command executes before 
the previously described command. 

In a batch job, command level zero is defined as the command procedure that 
is submitted for batch execution. If the batch job contains an @ command, 
then the commands in the nested procedure are executed at command level 
1. In batch jobs, as in interactive mode, you can create up to 32 command 
levels. 
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1.3 Login Command Procedures 

Each time you log in, the system automatically executes login command 
procedures if they exist. The system also executes these procedures at the 
beginning of every batch job you submit. The system executes two types of 
login command procedures: 

• A system (or group) login command procedure 

• Your personal login command procedure 

These login procedures are described in the following sections. 


1.3.1 A System or Group-Defined Login Command Procedure 

If a systemwide (or groupwide) login command procedure exists, it is 
executed before your personal login command procedure. When the system 
login command procedure terminates, it passes control to your personal 
login command procedure. System and group login command procedures 
allow your system manager to make sure that certain commands are always 
executed when you log in. 

To establish a system or group login command procedure, your system 
manager equates the logical name SYS$SYLOGIN to the appropriate login 
command procedure. Your system manager can specify that this login 
command procedure be used for all system users or for a certain group of 
users. 


1.3.2 Your Personal Login Command Procedure 

After executing a system or group login command procedure, the system 
executes your personal login command procedure. Use your personal login 
command procedure to execute the same commands each time you log in. 
Name your login command procedure LOGIN.COM and place it in your 
default login directory, unless your system manager tells you otherwise. 

The following sample LOGIN.COM procedure illustrates some techniques 
you can use when writing your login command procedure. 
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$! Exit if this is a batch job or another 
$! type of noninteractive process 
$! 

$ IF F$M0DE() .NES. "INTERACTIVE" THEN EXIT O 
$! 

$! Execute command procedures that contain 

$! my symbol, logical name, and keypad definitions 

$! 

$ 0DISK3:[MARCIA]SYMBOLS © 

$ 0DISK3: [MARCIA]LOGICALS © 

$ 0DISK3:[MARCIA]KEYDEF © 

$! 

$! Change my prompt string to an abbreviation 
$! of my node name 
$! 

$ NODE = F$GETSYI("NODENAME") © 

$ PROMPT = F$EXTRACT(0,3,NODE) 

$ SET PROMPT = "* * PROMPT *> " 

$! 

$! Type the system notices © 

$ TYPE SYS$SYSTEM:NOTICE.TXT 
$! 

$! Run a program that displays today’s appointments © 

$ RUN DISK3:[MARCIA.PROG]REMINDER 

O The F$MODE lexical function returns the mode (interactive, batch, 

network or other) that the process is in when the LOGIN.COM procedure 
is being executed. This statement causes the procedure to exit unless 
you are using the system interactively. You should test the mode at the 
beginning of your LOGIN.COM procedure to ensure that commands used 
only in interactive mode are not executed in any other mode; in some 
cases these commands can abort noninteractive processes. 

© In this example, the symbols, logical names, and keypad definitions are 
kept in separate files because they are easier to maintain. Also, this keeps 
the LOGIN.COM procedure easier to read. However, if you prefer, you 
can keep your symbols, logical names, and keypad definitions in your 
LOGIN.COM procedure. 

This command executes a command procedure that creates symbol 
assignments. Use symbols to create special abbreviations for commands 
you enter frequently. You must define global symbols or the symbols will 
be deleted after the command procedure exits. The following example 
shows global symbol definitions in a sample SYMBOLS.COM file: 

$ DISPLAY == "MONITOR PROCESSES/TOPCPU" 

$ GO == "SET DEFAULT" 

$ LP == "SHOW QUEUE/ALL SYS$PRINT" 

$ SS == "SHOW SYMBOL" 

$ REM == "(3DISK3:[MARCIA.PROG]REMINDER" 

$ MAIN == "SET DEFAULT DISK3:[MARCIA]" 

© This command executes a command procedure that defines logical names. 
Use logical names to refer to files or directories that you access often. You 
can also use logical names to refer to user names. 
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The following example shows a sample LOGICALS.COM file: 

$! Directories 
$ DEFINE HOME DISK3: [MARCIA] 

$ DEFINE REV DISK3:[MARCIA.REVIEWS] 

$ DEFINE TOOLS DISK3:[MARCIA.TOOLS] 

1! Files 

$ DEFINE EQUIP DISK3:[MARCIA.LISTS]EQUIPMENT.DAT 
$! 

$! Users 

$ DEFINE JON DAISY::HARRIS 
$ DEFINE JANE DAISY::MOORE 

O This command executes a command procedure that sets up DCL keypad 
definitions. You can press a defined key to enter an entire command (or 
a command segment) with one keystroke. The following example shows 
keypad definitions in a sample KEYDEF.COM file: 

$ DEFINE/KEY PF3 "SHOW USERS" /TERMINATE 
$ DEFINE/KEY KP7 "SPAWN" /TERMINATE 
$ DEFINE/KEY KP8 "ATTACH " 

$ DEFINE/KEY KP4 "SET HOST " 

© This group of commands determines the name of the node you are 
logging into and changes the DCL prompt to reflect the node name. 

The F$GETSYI lexical function determines the node name and the 
F$EXTRACT lexical function extracts the first three characters of the 
name. The SET PROMPT command changes the prompt from a dollar 
sign to the first three characters of the node name. 

© This command displays the system notices that your system manager 
keeps in the file SYS$SYSTEM:NOTICE.TXT. 

O This command runs a program that displays your daily appointments. If 
you have programs that you always run after you log in, you may prefer 
to execute them directly from your LOGIN.COM file. 

The system manager assigns the file specification for your login command 
procedure in the LGICMD field for your account. Accounts are maintained 
in the user authorization file (UAF). In most installations, the login command 
procedure is called LOGIN.COM. However, if you want to execute a file 
other than the one named in the LGICMD field for your account, use 
the /COMMAND qualifier when you log in. See the description of the 
login procedure in the VMS DCL Dictionary for information on using the 
/COMMAND qualifier. 
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Your system manager can set up a captive account by placing the name of a 
special command procedure in the LGICMD field for your account. If you log 
into a captive account, you can perform only the functions specified in the 
command procedure listed in the LGICMD field of your account; you cannot 
use the complete set of DCL commands. For more information on captive 
accounts, see the Guide to Setting Up a VMS System. 


1.4 Using a Command Procedure to Define Parameters or Qualifiers 

You can create a command procedure that specifies only parameters or 
qualifiers and then use the command procedure within a DCL command 
string. This type of command procedure is useful when there is a set of 
parameters or qualifiers that you frequently use with one or more particular 
commands. To execute the command procedure, use the execute procedure 
(@) command in the command string where you would normally use the 
qualifiers or parameters. 

For example, suppose you frequently use the same set of qualifiers when 
you enter the LINK command. You could create a command procedure that 
contains the following qualifiers: 

$!This command procedure contains command qualifiers 
$!for the LINK command 
$! 

/DEBUG/SYMBOL_TABLE/MAP/FULL/CROSS_REFERENCE 

To use this command procedure, execute it on the command line where you 
would otherwise place the qualifiers. For example, if you name the command 
procedure DEFLINK.COM, you would use the following command line to 
link to an object module named SYNAPSE.OBJ using the qualifiers that you 
specified in the command procedure: 

$ LINK SYNAPSEODEFLINK 

Note that you cannot include a space before the @ character when the 
command procedure begins with a qualifier name. 

The next example shows a command procedure named PARAM.COM that 
contains parameters: 

$!This command procedure contains parameters 
$!for the LINK command 
$! 

CHAP1, CHAP2 

To execute the procedure, use it in a command string in place of a parameter 
name: 

$ DIRECTORY OPARAM 

Note that the @ character must be preceded by a space when the command 
procedure begins with a parameter. 
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1.5 Testing and Debugging Command Procedures 

Typically, command procedures need to be tested, then debugged. You can 
debug command procedures by controlling the input and output to them and 
by using the SET VERIFY and SET NOVERIFY commands. When you enter 
the SET VERIFY command, the system displays the lines in the command 
procedure on your terminal while the procedure executes. 

The following example shows the execution of SYMBOLS.COM when 
verification is set: 

$ SET VERIFY 
$ QSYMBOLS 

$ DISPLAY == "MONITOR PROCESS/TOPCPU" 

$ GO == "SET DEFAULT" 

$ LP == "SHOW QUEUE/ALL SYS$PRINT" 

$ SS == "SHOW SYMBOL" 

$ REM == "0DISK3:[MARCIA.TOOLS]REMINDER" 

$ MAIN == "SET DEFAULT DISK3:[MARCIA]" 

$ 

Verification remains in effect until you enter the SET NOVERIFY command 
or use the F$VERIFY lexical function to change the verification setting. 
Chapter 4 contains more information on changing verification settings. 


1.6 Maintaining Command Procedures 

Command procedures are easy to maintain if you format them correctly, 
document them adequately, and verify that they execute. New versions of 
the VMS operating system may include enhancements to the DCL command 
language and changes to current commands that require you to make changes 
to a command procedure. 

Generally, DIGITAL makes changes to DCL commands (and to functions of 
the DCL command interpreter) only to add new features and to correct errors. 
However, a new release may occasionally change the format or results of 
a particular command, command parameter, or qualifier. To maintain your 
command procedures effectively, read the release notes issued with each VMS 
release. 
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This chapter describes how to use logical names, process permanent files, 
symbols, expressions, and lexical functions. You will use logical names, 
symbols, expressions, and lexical functions as variables within command 
procedures that resemble high-level language programs. (A variable is a 
placeholder that represents a value that can change each time a command 
procedure runs.) 


The information in this chapter will help you understand the examples in 
later chapters of this manual. If you are already familiar with these topics, 
skip this chapter and go to Chapter 3. For a more basic introduction, see the 
Introduction to VMS; for complete reference information, see the VMS DCL 
Concepts Manual. 


2.1 





Logical Names 

A logical name is a name that can be used in place of another character string. 
A logical name is equated to a string (called an equivalence string), or to a list 
of strings (called a search list). When you use a logical name, the equivalence 
string is substituted for the logical name. The most common reason for using 
logical names is to represent files, directories, and devices. 

For example, if the logical name TEST-FILE is equated to the equivalence 
string STATISTICS you can enter the following command: 

$ RUN TEST.FILE 

The system substitutes the equivalence string STATISTICS for the logical 
name TEST-FILE and runs the program STATISTICS.EXE. (The RUN 
command supplies the default file type EXE.) 

In general, whenever a command accepts a file or a device name, the 
command checks whether the name you provide is a logical name. If the 
name is a logical name, then the system replaces the logical name with its 
actual value and executes the appropriate command. 

When the system translates a logical name and replaces the logical name with 
its equivalence string, the system examines the equivalence string to see if it 
is also a logical name. If it is, the system performs a second translation. This 
process, called iterative translation, can occur a maximum of 10 times. 
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2.1.1 Creating and Deleting Logical Names 

You can use the ASSIGN or DEFINE commands to create a logical name; 
this section demonstrates the DEFINE command. (Note that syntax for the 
ASSIGN command differs from the syntax for the DEFINE command. For 
information on using the ASSIGN command, see the VMS DCL Dictionary.) 

The syntax for defining a logical name is as follows: 

$ DEFINE logical-name equivalence-name[,...] 

For example, the following command creates the logical name WORKFILE 
and equates it to the equivalence string DISK2:[WALSH.REPORTS]WORK_ 
SUMMARY.DAT: 

$ DEFINE WORKFILE DISK2:[WALSH.REPORTS]WORK.SUMMARY.DAT 

Use the DEASSIGN command to delete a logical name. For example, if you 
no longer want to keep the logical name WORKFILE, you can delete it with 
the following command: 

$ DEASSIGN WORKFILE 


2.1.2 Using Logical Names 

When you use the system interactively, you can use logical names to refer to 
your files and work directories. For example, if you create the logical name 
COMS to translate to the directory name DISK7:[WALSH.COMMAND_ 
PROC], you can use the name COMS instead of typing the long device and 
directory names. The following example shows how to define the logical 
name COMS and use it as part of a file specification. 

$ DEFINE COMS DISK7:[WALSH.COMMAND.PROC] 

$ TYPE COMS:PAYROLL.COM 
$ SET DEFAULT COMS 

Note that when you use a logical name as part of a file specification, the 
logical name must be at the beginning (leftmost) part of the file specification, 
and must be followed by a colon. There are, however, special rules for 
using logical names in network file specifications. See the VMS DCL Concepts 
Manual for more information. 

Logical names are also used to refer to the devices on your system. You 
should not refer to a device using its physical device name (such as DBA1); 
instead you should use the logical name assigned by your system manager. 
Also, certain commands such as ALLOCATE and MOUNT allow you to create 
your own logical names when you work with disks and tapes. 

In command procedures, you will often use logical names when performing 
input and output from files. When you open a file with the OPEN command, 
you also create a logical name for the file. The READ, WRITE, and CLOSE 
commands use the logical name, not the actual file specification, to refer to 
the file. For example: 

$ OPEN INFILE DISK3:[WALSHlDATA.DAT 
$ READ INFILE RECORD 
$ CLOSE INFILE 

When closing the file, the CLOSE command deassigns the logical name 
INFILE. 
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2.1.3 


Logical Name Tables 


The system maintains logical names in logical name tables. Some logical 
name tables are available only to your process. Others are shareable, they are 
available to other users on the system. In general, the names you work with 
are in the following four tables: 

Process table The names in this table are available only to your process. 

The actual name for your process table is LNM$PROCESS_ 
TABLE. However, use the logical name LNM$PROCESS to 
refer to your process table. 


Job table The names in this table are available to your process, and 

to any of your subprocesses. The actual name for your 
job table is LNM$JOB_xxx (xxx represents a job number.) 
However, use the logical name LNM$JOB to refer to your job 
table. 

Group table The names in this table are available to all users in 

your group. The actual name for your group table is 
LNM$GROUP_xxx (xxx represents a group number.) 
However, use the logical name LNM$GROUP to refer to 
your group table. 


System table The names in this table are available to all users on 

the system. The actual name for your system table is 
LNM$SYSTEM_TABLE. However, use the logical name 
LNMSSYSTEM to refer to the system table. 


When you use a logical name, the system looks in the process, job, group, 
and system tables (in that order) to obtain the name's translation. You can, 
however, change the way that the system translates logical names; see the 
VMS DCL Concepts Manual for more information. 

By default, the DEFINE and DEASSIGN commands place and delete names 
from your process table. However, you can request a different table with the 
/TABLE qualifier. For example: 

$ DEFINE/TABLE=LNM$SYSTEM REVIEWERS DISK3: [PUBLIC]REVIEWERS.DIS 

Note that you need special privileges to place or delete names in the group or 
system tables; see the VMS DCL Concepts Manual for more information. 

Most of the time you will create logical names in your process table. However 
if you are a system manager or if your work requires you to add names to 
shareable tables, you will need to work with the group and system tables. See 
the VMS DCL Concepts Manual for more information on the special privileges 
you need to work with shareable tables. 

You can create logical name tables in addition to those provided by the VMS 
operating system. To create additional tables, use the CREATE/NAME— 
TABLE command. 

The system maintains logical name tables in two types of directories: a 
process-private directory (LNM$PROCESS—DIRECTORY) and a shareable 
directory (LNM$SYSTEM_DIRECTORY). There is only one shareable 
directory table for your system, but each process has its own process-private 
directory. All logical name tables and any logical names that translate to 
tables are kept in these directory tables. For example, your table names 
LNM$PROCESS, LNM$JOB, and LNM$GROUP are kept in your process- 
private directory; LNM$SYSTEM is kept in the shareable directory. 
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2.1.4 Displaying Logical Names 

Use the SHOW LOGICAL command to display logical names and their 
equivalence strings. The SHOW LOGICAL command searches certain logical 
name tables for the name (or names) you specify. If you do not specify a 
table to be searched, the SHOW LOGICAL command searches your process, 
job, group, and system tables. However, you can change the default search 
order, or you can specify other logical name tables to be searched. 

The following command displays the equivalence string for the logical name 
INTRO: 

$ SHOW LOGICAL INTRO 

"INTRO" = "DISK6:[OCONNELL.INTRO]" (LNM$PROCESS_TABLE) 

This command uses the default search order and searches the process, job, 
group, and system tables for the logical name INTRO. The SHOW LOGICAL 
command displays the logical name, its translation, and the table where the 
logical name was found. 

If you do not specify a name with the SHOW LOGICAL command, then all 
names in the process, job, group, and system tables are displayed unless you 
have changed your default search order. 

Note that you can use the /TABLE qualifier to specify a table for the SHOW 
LOGICAL command to search. For example, if you enter the command 
SHOW LOGICAL/TABLE=LNM$PROCESS, names in the process table are 
displayed. 


2.1.5 Access Modes and Attributes 

Logical names have access modes and attributes that are associated with the 
names. (The SHOW LOGICAL/FULL command displays these modes and 
attributes.) When you create a logical name, the name is created in supervisor 
mode unless you use a qualifier to specify a different mode. No attributes are 
applied unless you explicitly request them. 

In command procedures, you usually create names in supervisor mode. 
However, sometimes you may want to create a temporary logical name 
assignment that lasts only for the execution of one command. To create a 
temporary logical name, use the DEFINE command with the /USER_MODE 
qualifier. (See Chapter 3 for more information.) 

For more information on access modes and attributes, see the VMS DCL 
Concepts Manual. 


2.1.6 Search Lists 

A search list is a logical name that has more than one equivalence string. For 
example: 

$ DEFINE MY_FILES DISKI:[COOPER], DISK2:[COOPER] 

You can use a search list in any place you can use a logical name. When you 
use a search list, the system translates the search list using each equivalence 
string in the search list definition. For example: 


2-4 








DCL Concepts 

2.1 Logical Names 


$ TYPE MY_FILES:CHAP1.RNO 

This command attempts to type the file DISK l:[COOPER]CH API.RNO. 

If this file does not exist, the system will look for the file 
DISK2:[COOPER]CHAPl .RNO. 

For more information on how commands process search lists, see the VMS 
DCL Concepts Manual. 


2.1.7 System-Defined Logical Names 

When your system is booted (that is, when the operating system is started 
up), a set of systemwide logical names are created and placed in the system 
logical name table (LNM$SYSTEM). These logical names allow you to refer to 
commonly used files or devices without remembering their actual names. For 
example, if you want a list of your operating system's programs, you do not 
need to know the name of the disk and directory where these programs are 
stored. Instead, you can use the logical name SYS$SYSTEM as shown: 

$ DIRECTORY SYS$SYSTEM 

See the VMS DCL Concepts Manual for a complete list of systemwide logical 
names. 

Every time you log in, the system creates a group of logical names for your 
process and places these names in your process table. For example, the logical 
name SYS$LOGIN refers to your default device and directory when you log 
in. If you have changed your current defaults by using the SET DEFAULT 
command, you can use the following command to display a file from your 
initial default directory: 

$ TYPE SYS$L0GIN:DAILY_NOTES.DAT 

For a complete list of your default process logical names, see the VMS DCL 
Concepts Manual. Note that four of your default process logical names refer to 
process permanent files; these are described in Section 2.2.1. 


2.2 Process Permanent Files 

Process permanent files are files that can remain open for the life of your 
process. By default, DCL creates four process permanent files for you when 
you log in. In addition, anytime you enter a command that opens a file, DCL 
opens the file as a process permanent file. For example, if you open a file 
with the OPEN command, this file is opened as a process permanent file. The 
file remains open until you explicitly close the file, or until you log out. 

Process permanent files are stored in a special area in memory. Note that if 
you keep a large number of files open at the same time, you can exhaust this 
area. If this occurs, close some of the files (or log out). 
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2.2.1 


Default Process Permanent Files 

By default, DCL creates and assigns logical names to four process permanent 
files. You often use these names in command procedures to do things such as 
read data from the terminal and display data. (See Chapter 3.) 

The default process permanent files are as follows: 


SYS$COMMAND 


SYS$ERROR 

SYS$INPUT 

SYSSOUTPUT 


The initial file from which DCL reads input. (A file from which 
DCL reads input is called an input stream.) The command 
interpreter uses SYS$COMMAND to "remember" the original 
input stream. 

The default file to which DCL writes error messages generated 
by warnings, errors and severe errors. 

The default file from which DCL reads input. 

The default file to which DCL writes output. (A file to which 
DCL writes output is called an output stream.) 


If you use the SHOW LOGICAL command to determine the equivalence 
string for a process permanent file, only the device portion of the string is 
displayed. For example: 


$ SHOW LOGICAL/FULL SYS$INPUT 

M SYS$INPUT" [exec] = "_TTB4: M [concealed,terminal] (LNM$PROCESS_TABLE) 

However, the equivalence strings for process permanent files also contain 

special characters that the system uses to locate the correct files. The system 

uses these special characters internally and does not display them to users. 

When you use the system interactively, DCL equates SYS$INPUT, 

SYS$OUTPUT, and SYS$ERROR and SYS$COMMAND to your terminal. 

However, when you execute command procedures and submit batch jobs, 

DCL creates new equivalences for these logical names. 

When you execute a command procedure interactively, the following occurs: 

• SYS$INPUT is equated to the command procedure; therefore, DCL 
obtains data from the command procedure. This assignment is temporary. 
After the command procedure terminates, SYS$INPUT has its original 
value. 

• SYS$OUTPUT, SYS$COMMAND, and SYS$ERROR remain equated to 
the terminal. 


When you submit a batch job, the following occurs: 

• SYS$INPUT and SYS$COMMAND are equated to the batch job 
command procedure. 

• SYS$OUTPUT and SYS$ERROR are equated to the batch job log file. 


When you nest command procedures, the equivalence for SYS$INPUT 
changes to point to the command procedure that is currently executing. 
However, the equivalences for SYS$OUTPUT, SYS$ERROR, and 
SYS$COMMAND remain the same unless you explicitly change them. 
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2.2.2 Redefining System-Defined Logical Names 

DCL provides default values for SYS$INPUT, SYS$OUTPUT, SYS$ERROR, 
and SYS$COMMAND that you ordinarily need not change. However, when 
you want to perform certain input and output operations, as described in 
Chapter 3, you must change these equivalences. 

For information on redefining the default process permanent files, see the 
VMS DCL Concepts Manual. 


2.3 Symbols 

A symbol is a name that represents a numeric, character, or logical value. 
When you use a symbol in a DCL command line, DCL replaces the symbol 
with its value. For example, you can enter the following command to equate 
the symbol LP to the command SHOW QUEUE/ALL SYS$PRINT: 

$ LP = "SHOW QUEUE/ALL SYS$PRINT" 

After defining the symbol, you can enter the following: 

$ LP 

DCL will substitute the string SHOW QUEUE/ALL SYS$PRINT for the 
symbol LP. 

In command procedures, symbols help you perform programming tasks. For 
example, you can use symbols as variables in expressions. You can also use 
symbols to pass parameters to and from command procedures. In addition, 
commands such as READ, WRITE, and INQUIRE use symbols to refer to data 
records. See Chapter 4 for more information on tasks you can perform using 
symbols. 


2.3.1 Types of Symbols 

You can create two types of symbols, local and global. Local symbols are 
accessible from the current command level, and from command procedures 
executed from the current command level. Global symbols are accessible at 
all command levels. Use an = (Assignment Statement) to create a symbol. 

To create a local symbol, use one equal sign; to create a global symbol, use 
two equal signs. In the following example, SS is a local symbol and GO is a 
global symbol. 

$ SS = "SHOW SYMBOL" 

$ GO == "SET DEFAULT" 

DCL places local symbols in the local symbol table for the current command 
level. DCL maintains a local symbol table for each command level as long as 
the command level is active; when a command level is no longer active, its 
local symbol table (and all the symbols it contains) is deleted. 

DCL maintains one global symbol table for the duration of the process and 
places all global symbols in that table. Therefore, a global symbol exists for 
the duration of the process, unless the symbol is explicitly deleted. 

When DCL determines the value of a symbol, it looks in the local symbol 
table for the current command level. If DCL does not find the symbol there, 
it searches in the local symbol tables for previous command levels. If it does 
not find the symbol, DCL then looks in the global symbol table. 
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2.3.2 Creating Symbols 


Use an assignment statement to create a symbol. An assignment statement 
has the following format: 

$ symbol =[=] expression 

The left side of the assignment statement defines the symbol name; the right 
side of the assignment statement contains an expression. When you create a 
symbol, DCL evaluates the expression and assigns the result to the symbol. If 
the evaluated expression is an integer, then the symbol has an integer value. 
If the expression evaluates to a character string, then the symbol has a string 
value. If you used two equal signs, the symbol is a global symbol; if you used 
one equal sign, the symbol is a local symbol. 

The following example creates a local symbol and a global symbol: 

$ SUM =5+7 

$ NAME == "MORTIMER" + " SNERD" 

The local symbol SUM has an integer value because the expression (5 + 

7) evaluates to an integer (12). The global symbol NAME has a string value 
because the expression evaluates to a character string ("MORTIMER SNERD"). 
Note that you must enclose character strings in quotation marks when they 
are used in expressions. 


2.3.3 Displaying the Value of a Symbol 

Use the SHOW SYMBOL command to display the value of a symbol. For 
example: 

$ SHOW SYMBOL SUM 

SUM = 12 Hex = 0000000C Octal = 00000000014 
$ SHOW SYMBOL NAME 

NAME == "MORTIMER SNERD" 

Note that when a symbol has an integer value, the SHOW SYMBOL 
command displays the value in decimal, hexadecimal, and octal notation. 


2.3.4 Masking the Value of Symbols 

The SET SYMBOL command masks the values of local and global symbols 
without deleting these symbols. Use the SET SYMBOL command to isolate 
the local or global symbols in a command procedure from the symbols 
defined in other command procedures. For example, if your complex 
command procedure executes another command procedure, you can use 
the same symbol names in both procedures if you specify the SET SYMBOL 
command in the second command procedure. 

The SET SYMBOL/SCOPE=NOLOCAL command causes all local symbols 
defined at an outer procedure level to be inaccessible to the current procedure 
level and any inner level. For example, if you specify the SET SYMBOL 
/SCOPE=NOLOCAL command at procedure levels 2 and 4, procedure level 
2 can access only level 2 local symbols. Procedure level 3 can access levels 2 
and 3 local symbols, and level 4 can access only level 4 local symbols. 
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The SET SYMBOL/SCOPE=NOGLOBAL command causes all global symbols 
to become inaccessible for all subsequent commands in the current and inner 
procedure levels until either the SET SYMBOL/SCOPE=GLOBAL command 
is specified or the procedure exits to a level at which global symbols were 
accessible. 


2.3.5 Deleting Symbols 

You can delete local symbols with the DELETE/SYMBOL command. By 
default, DELETE/SYMBOL attempts to delete symbols from the current 
local symbol table. If you want to delete a global symbol, you must use the 
/GLOBAL qualifier. To delete the global symbol GO, enter the following 
command: 

$ DELETE/SYMBOL/GLOBAL GO 


2.4 Expressions 

Expressions are values or groups of values that DCL evaluates. There are two 
types of expressions: 

• Integer expression—an expression that evaluates to an integer 

• Character string expression—an expression that evaluates to a character 
string 

Expressions are used in symbol assignment statements (on the right side of 
the equal sign), in IF statements, in WRITE commands, and as arguments for 
lexical functions. 

Expressions can contain character strings, integers, lexical functions, symbols 
or combinations of these values. When used in expressions, these values 
are called operands. If an expression contains more than one operand, 
the operands are connected by operators that specify the operations to be 
performed. The following examples illustrate expressions: 

Y = 25 This integer expression contains only one 

operand, the number 25. Therefore, the 
value 25 is assigned to the symbol Y. 

X = Y - 8 This integer expression contains two 

operands: Y and 8. Y is a symbol and 
8 is an integer. The minus sign is an 
operator indicating subtraction. When 
DCL evaluates this expression, it replaces 
the symbol Y with its actual value and 
performs the subtraction. 

TITLE = "TWELFTH" + " NIGHT" This string expression contains two 

operands: "TWELFTH" and ” NIGHT". 
Because both operands are character 
strings, the plus sign indicates that the 
strings should be concatenated. When 
DCL evaluates this expression, the result is 
"TWELFTH NIGHT". 
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IF COUNT .EQ. 4 THEN EXIT In this IF statement, DCL determines 

whether the integer expression COUNT 
.EQ. 4 is true. DCL replaces the symbol 
COUNT with its actual value and tests 
whether it equals 4. If it does, then the 
command procedure exits. 


2.4.1 Values in Expressions 

The following sections describe values that can be used in expressions. These 
values include the following: 

• Character strings 

• Integers 

• Symbols 

• Lexical functions 


2.4.1.1 Character Strings 

When you use a character string in an expression, you must enclose it in 
quotation marks. (If you do not use quotation marks, DCL processes the 
string as a symbol.) To include quotation marks within a string, type two 
consecutive quotation marks. For example: 

$ PROMPT = "Type ""YES"" or ""NO""" 

$ SHOW SYMBOL PROMPT 

PROMPT = "Type "YES" or "NO"" 

To continue a character string over two lines, use a plus sign (for string 
concatenation) and a hyphen (for continuation): 

$ ADVICE = "A STITCH IN TIME " + - 
_$ "SAVES NINE" 

$ SHOW SYMBOL ADVICE 

ADVICE = "A STITCH IN TIME SAVES NINE" 

You cannot use the hyphen continuation character within a quoted character 
string. 


2.4.1.2 Integers 

Specify integers as decimal numbers (numbers in base 10) unless you use 
the radix operator %X (for hexadecimal) or %0 (for octal). Do not place 
quotation marks around integers. For example: 

$ NUM = 17 
$ HEXNUM = °/,XlAB 
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2.4.1.3 Symbols 

When you use a symbol in an expression, the symbol's value is automatically 
substituted for the symbol; do not surround the symbol name with quotation 
marks. The following example uses the symbol COUNT in an expression: 

$ COUNT = 3 
$ TOTAL = COUNT + 1 
$ SHOW SYMBOL TOTAL 

TOTAL = 4 Hex = 00000004 Octal = 00000000004 

The value for COUNT (3) is automatically substituted when the expression is 
evaluated and the result is assigned to the symbol TOTAL. 

Remember that when you use symbols within character strings, you must 
use apostrophes to request symbol substitution. See Section 2.5.1 for more 
information. 


2.4.1.4 Lexical Functions 

Lexical functions return information about an item or a list of items. (These 
items are called arguments.) You invoke a lexical function by typing its name 
and its argument list. You must always surround the argument list with 
parentheses. 

When you specify arguments for lexical functions, follow the rules for writing 
expressions: enclose character strings in quotation marks; do not enclose 
integers, symbols, and lexical functions in quotation marks. 

You can use lexical functions in expressions in the same way you would 
normally use character strings, integers, and symbols. When you use a lexical 
function in an expression, DCL automatically evaluates the function and 
replaces the function with its return value. For example: 

$ SUM = F$LENGTH("BUMBLEBEE") + 1 
$ SHOW SYMBOL SUM 

SUM = 10 Hex = 0000000A Octal = 00000000012 

The F$LENGTH function returns the length of the value specified as its 
argument. DCL automatically determines the return value (9) and uses this 
value to evaluate the expression. Therefore, the result of the expression (9 + 
1) is 10, and this value is assigned to the symbol SUM. 

Note that each lexical function returns information as either an integer or a 
character string. Also, note that you must specify the arguments for a lexical 
function as either integer or character string expressions. 

For example, the F$LENGTH function requires an argument that is a character 
string expression, and it returns a value that is an integer. In the previous 
example, the argument "BUMBLEBEE" is a character string expression and the 
return value( 9) is an integer. 

The following examples show different ways you can specify the argument for 
the F$LENGTH function; in each example the argument is a character string 
expression. The first example shows a symbol that is used as an argument: 

$ BUG = "BUMBLEBEE" 

$ LEN = F$LENGTH(BUG) 

$ SHOW SYMBOL LEN 

LEN = 9 Hex = 00000009 Octal = 00000000011 

When you use the symbol BUG as an argument, do not place quotation 
marks around it. The lexical function automatically substitutes the value 
"BUMBLEBEE" for BUG, determines the length, and returns the value 9. 
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This example shows an argument that contains both a symbol and a character 
string: 

$ BUG = "BUMBLEBEE" 

$ LEN = F$LENGTH(BUG) 

$ SHOW SYMBOL LEN 

LEN =9 Hex = 00000009 Octal = 00000000011 
$ LEN = F$LENGTH(BUG + "S") 

$ SHOW SYMBOL LEN 

LEN = 10 Hex = 0000000A Octal = 00000000012 

The symbol BUG is not enclosed in quotation marks, but the string "S" is. The 
argument must be evaluated before the F$LENGTH function can determine 
the length. The value represented by the symbol BUG ("BUMBLEBEE") 
is concatenated with the string "S"; the result is "BUMBLEBEES". The 
F$LENGTH function determines the length of the string "BUMBLEBEES" 
and returns the value 10. 

The next example uses another lexical function as the argument for the 
F$LENGTH function. (The F$DIRECTORY function returns the name of your 
current default directory, including the square brackets. In this example, the 
current default directory is [SALMON].) 

$ LEN = F$LENGTH(F$DIRECT0RY()) 

$ SHOW SYMBOL LEN 

LEN =8 Hex = 00000008 Octal = 00000000010 

Do not place quotation marks around the F$DIRECTORY function when it is 
used as an argument; the function is automatically evaluated. The result of 
the F$DIRECTORY function must be returned before the F$LENGTH function 
can determine the length. Then, the F$LENGTH function determines the 
length of your default directory, including the square brackets. 

Appendix B gives a brief description of each lexical function. For complete 
information, see the Lexical Functions section in the VMS DCL Dictionary. 


2.4.2 Operators Used in Expressions 

When an expression has more than one operand, the operands are connected 
by operators. Table 2-1 lists the operators in the order in which they are 
evaluated if there are two or more operators in an expression. The operators 
are listed from highest to lowest precedence; that is, operators at the top 
of the table are performed before operators at the bottom. If an expression 
contains operators that have the same order of precedence, the operations are 
performed from left to right. 

You can override the normal order of precedence by using parentheses. For 
example: 

$ RESULT = 4 * (6 + 2) 

$ SHOW SYMBOL RESULT 

RESULT = 32 Hex = 00000020 Octal = 00000000040 

In this example, the parentheses force the addition to be performed before the 
multiplication. If you had not used the parentheses, the multiplication would 
have been performed first and the result would have been 26. See the VMS 
DCL Concepts Manual for complete information on using each operator. 
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Table 2—1 Summary of Operators in Expressions 


Operator 

Precedence 

Description 

+ 

7 

Indicates a positive number 

- 

7 

Indicates a negative number 

« 

6 

Multiplies two numbers 

/ 

6 

Divides two numbers 

+ 

5 

Adds two numbers or concatenates two character 
strings 

- 

5 

Subtracts two numbers or reduces a string 

.EQS. 

4 

Tests if two character strings are equal 

.GES. 

4 

Tests if first string is greater than or equal to 
second 

.GTS. 

4 

Tests if first string is greater than second 

.LES. 

4 

Tests if first string is less than or equal to second 

.LTS. 

4 

Tests if first string is less than second 

.NES. 

4 

Tests if two strings are not equal 

.EQ. 

4 

Tests if two numbers are equal 

.GE. 

4 

Tests if first number is greater than or equal to 
second 

.GT. 

4 

Tests if first number is greater than second 

.LE. 

4 

Tests if first number is less than or equal to 
second 

.LT. 

4 

Tests if first number is less than second 

.NE. 

4 

Tests if two numbers are not equal 

.NOT. 

3 

Logically negates a number 

.AND. 

2 

Combines two numbers with a logical AND 

.OR. 

1 

Combines two numbers with a logical OR 


When you write expressions that contain two or more values connected by 
operators, the values should all have the same data type. Values either have 
string or integer data types. String data includes character strings, symbols 
with string values, and lexical functions that return string values. Integer 
data includes integers, symbols with integer values, and lexical functions that 
return integer values. 

If you use different data types, DCL converts values to the same type before 
evaluating the expression. In general, if you use both string and integer 
values, the string values are converted to integers. The only exception is 
when DCL performs string comparisons; in these comparisons, integers are 
converted to strings. See the VMS DCL Concepts Manual for more information 
on how DCL converts integers to strings, and strings to integers. 
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2.5 Symbol Substitution 

In certain contexts, DCL assumes that a string of characters beginning with a 
letter is a symbol name or a lexical function. In these contexts, DCL tries to 
replace the symbol or lexical function with its value. If you use a symbol or 
lexical function in any other context, you must use a substitution operator to 
request symbol substitution. 

DCL automatically evaluates symbols and lexical functions when they are 
used in expressions. Therefore, DCL evaluates symbols and lexical functions 
automatically when they are as follows: 

• On the right side of an = or == assignment statement 

• In an argument for a lexical function 

• In a DEPOSIT, EXAMINE, IF, or WRITE command 

In addition, DCL evaluates symbols at the beginning of a line when the 
symbol is not followed by an equal sign or a colon. (The examples in the 
previous sections used symbols and lexical functions in places where they 
were automatically evaluated.) 

You can use symbols and lexical functions in other places in command lines 
if you use special operators to request symbol substitution. In general, use 
apostrophes to request symbol substitution. There are special cases where 
you must use an ampersand instead. 


2.5.1 Using Apostrophes as Substitution Operators 

Use apostrophes to request symbol substitution when you use symbols and 
lexical functions in places where they are not automatically substituted. Place 
apostrophes around the symbol for which you are requesting substitution. 

For example: 

$ FILENAME = "CALENDAR.DAT" 

$ TYPE ’FILENAME’ 

In this example, the apostrophes indicate that FILENAME is a symbol that 
DCL should translate. If the symbol FILENAME is equated to the string 
"CALENDAR.DAT", then the file CALENDAR.DAT is displayed. If you had 
not included the apostrophes, DCL would not have performed the symbol 
substitution. 

You can use apostrophes to perform symbol substitution when you 
concatenate two symbol names, as follows: 

$ NAME = "EXAMPLES" 

$ TYPE = ".TST" 

$ PRINT ’NAME’’TYPE’ 

When the command is executed, the values for NAME and TYPE are 
substituted for the symbols. The two strings "EXAMPLES" and ".TST" are 
concatenated, forming the file name "EXAMPLES.TST". 

To request symbol substitution for a symbol within a character string, place 
two apostrophes before the symbol name and one apostrophe after it. For 
example: 
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$ PROMPT.STRING = "Creating file ’’FILENAME’.TST" 

If the current value of the symbol FILENAME is the string "BUGS", the result 
of the symbol substitution is the string "Creating file BUGS.TST". 


2.5.2 Using Ampersands as Substitution Operators 

The ampersand can also be used to request symbol substitution. The 
difference between the apostrophe and the ampersand is the time when 
substitution occurs. Symbols preceded by apostrophes are substituted 
during the first phase of DCL command processing; symbols preceded by 
ampersands are substituted during the second phase. Sometimes, the result 
of using these operators is the same: 

$ TYPE ’FILENAME’ 

$ TYPE ^FILENAME 

If symbol FILENAME is equated to the string "BUGS", then both commands 
will type the file BUGS.LIS. (The TYPE command provides the default file 
type LIS.) 

However, sometimes you must use the ampersand to get the correct results. 
For example, when you pass parameters to a command procedure these 
parameters are equated to the symbols PI through P8. You may need to use 
the following syntax when you are refering to parameters that were passed to 
a procedure: 

$ PRINT &P’COUNT’ 

In this example, you want to print the file indicated by the first parameter, 
PI. First, DCL replaces the symbol COUNT with its value. If its value were 
1, the resulting string would be as follows: 

$ PRINT &P1 

Next, DCL performs the substitution requested by the ampersand, and 
substitutes the appropriate value for PI. If PI were COMMENTS.DAT, the 
resulting string would be as follows: 

$ PRINT COMMENTS.DAT 

In general, do not use the ampersand for symbol substitution unless it is 
required to translate your symbols correctly. For complete information on 
symbol substitution, see the VMS DCL Concepts Manual. 


2.5.3 Distinguishing between Symbols and Logical Names 

It is easy to confuse symbols and logical names, especially when symbols 
are used in place of file specifications (as shown in some previous examples). 
The main difference between logical names and symbols is the manner in 
which they are translated: DCL performs symbol substitution, but utilities 
and programs perform logical name translation. 

When you enter a command string, DCL examines the string to make sure it 
is valid. While examining the string, DCL checks for symbols in the places 
where it expects to find symbols. DCL also checks for symbols in places 
indicated by substitution operators. After DCL evaluates the command string, 
the command starts to execute. The command must then examine the file or 
device specification to determine what file to process. When doing this, the 
command checks whether the specification contains a logical name. 
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This chapter describes how to send input to and receive output from 
command procedures. It discusses the following topics: 

• Passing input data to command procedures and to commands and images 
you execute from within command procedures 

• Controlling output from command procedures 

• Displaying information at the terminal 


3.1 Passing Data to Command Procedures 

You may need to pass input data to a command procedure when you execute 
the command procedure. DCL provides three ways to pass this input data: 

• Passing data to a command procedure using parameters 

• Issuing a prompt to the user at the terminal; the user enters data 
interactively. 

• Reading data from an input file. 

The following sections describe how to pass parameters and how to obtain 
data from a user at a terminal. See Chapter 6 for information on reading data 
from a file. 


3.1.1 Passing Parameters 

When you execute a command procedure interactively, you can pass up 
to eight parameters by placing the values of the parameters after the file 
specification of the command procedure. To pass parameters to a batch job, 
use the /PARAMETERS qualifier to the SUBMIT command. See Chapter 8 
for more information on passing parameters to batch jobs. 

Parameter values are assigned to the local symbols PI through P8. For 
example: 

$ 0C0PYS0RT INSORT.DAT OUTSORT.DAT 

When this command procedure is executed, two parameters are passed: 
INSORT.DAT and OUTSORT.DAT. The first parameter (PI) has the value 
INSORT.DAT; the second (P2) has the value OUTSORT.DAT. 

The command procedure COPYSORT.COM can then use the symbols PI and 
P2 to refer to the files it is processing. For example: 
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$ ! Copy and sort a file 
$ ! 

$ COPY ’PI’ USER.DISK:[MARY]*.* 

$ SORT ’PI’ ’P2’ 

$ EXIT 

This command procedure copies the file INSORT.DAT from your current 
default directory to USER_DISK:[MARY]*.*. Then, it sorts INSORT.DAT and 
places the sorted file in OUTSORT.DAT. 

By using parameters, you can process different files each time you run the 
procedure, but you do not need to rewrite the procedure. 

When you list parameters on a command line, separate them with one or 
more spaces, tabs, or both. To pass a null parameter, use a set of quotation 
marks as a place holder in the command string. For example: 

$ OCOPYFILES "" USER.DISK:[MARY]*.* 

When COPYFILES.COM is executed, PI will be a null string, but P2 will 
have the value "USER_DISK:[MARY]*.*". 

You can specify a parameter as an integer, a string, or a symbol. When you 
specify a parameter as an integer, the integer is converted to a string when it 
is assigned to one of the symbols PI through P8. For example: 

$ LADDER 24 25 

When you specify a parameter as a string, DCL automatically converts the 
letters in the string to uppercase. To preserve spaces, tabs, or lowercase 
letters, enclose the string in quotation marks. If you pass fewer than eight 
parameters, the extra symbols are assigned null string values. If you attempt 
to pass more than eight parameters, the system displays an error message and 
the command procedure does not execute. 

The following command procedure PARAMS.COM displays the parameters 
passed to the procedure: 

$ ! Displaying parameters 
$ SHOW SYMBOL/LOCAL/ALL 
$ EXIT 

You can execute the procedure with the following parameters: 

$ OPARAMS Paul Cramer 
P8 = "" 

P7 = •• •• 

P6 = "" 

P5 = "" 

P4 = •' »• 

P3 = "" 

P2 = "CRAMER" 

PI = "PAUL" 

PI is assigned the value "PAUL" and P2 is assigned the value "CRAMER"; 
the strings are converted to uppercase because they are not surrounded in 
quotation marks. 

The following command passes only one parameter, "Paul Cramer"; the 
quotation marks preserve the lowercase letters and spaces. 
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$ QPARAMS "Paul Cramer" 

P8 = "" 

py _ it ii 

P6 = "" 

P5 = "" 

P4 = ii ii 
P3 = "" 

P2 = "" 

PI = "Paul Cramer" 

To pass the value of a symbol, place apostrophe characters before and after 
the symbol. When passing the symbol, DCL removes quotation marks that 
enclose the string. The following commands create the symbol NAME and 
pass values PAUL and CRAMER to the command procedure SEARCH.COM. 

$ NAME = "Paul Cramer" 

$ 0SEARCH ’NAME’ 

When you enter a nested procedure, new symbols PI through P8 are created 
in the local symbol table for the nested procedure. These symbols are 
assigned values passed by the invoking procedure. 

The following example invokes SEARCH.COM, which in turn invokes the 
nested command procedure GETNAME.COM. 

$ OSEARCH "Paul Cramer" 


$ ! SEARCH.COM 
$ QGETNAME ’PI’ Joe Cooper 

Because PI in SEARCH.COM is the string Paul Cramer, which contains 
no quotation marks, it is passed to NAME.COM as two parameters. In 
NAME.COM, PI through P8 are defined as follows: 

PI = PAUL 
P2 = CRAMER 
P3 = JOE 
P4 = COOPER 
P5-P8 = Null 

Because DCL removes quotation marks when passing a symbol, to preserve 
spaces, tabs, and lowercase characters in a symbol value, you must enclose 
the value in three sets of quotation marks. In the following example, the 
literal value in PI is enclosed in three sets of quotation marks and passed to 
NAME.COM. If PI originally contained the value "Paul Cramer", the value 
"Paul Cramer" is passed to NAME.COM. 

$ ! DATA.COM 
$ QUOTE = 

$ PI = QUOTE + PI + QUOTE 
$ 0NAME ’PI’ "Joe Cooper" 

In this example, PI is Paul Cramer and P2 is Joe Cooper in the command 
procedure NAME.COM. 

An alternative is to enclose the text in quotation marks and, where a symbol 
appears, precede it with two apostrophes, and follow it with one apostrophe. 

$ ! DATA.COM 
$ SNAME "”P1’» 
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Prompting for Input 

You can use the INQUIRE command to prompt for input to be used by a 
command procedure. The INQUIRE command issues a prompt, reads the 
user's response from the terminal, and assigns it to a symbol. For example: 

$ INQUIRE FILE "Filename" 

This command issues the prompt "Filename: " to your terminal and assigns 
your response to the symbol FILE. By default, the INQUIRE command inserts 
a colon and a space at the end of the prompt string. You can suppress 
this with the /NOPUNCTUATION qualifier as described in the VMS DCL 
Dictionary. 

The INQUIRE command converts your response to uppercase, replaces 
multiple blanks and tabs with a single space, and removes leading and trailing 
spaces. The INQUIRE command also performs apostrophe substitution for 
symbols and lexical functions. To preserve lowercase characters, multiple 
spaces, and tabs, enclose your response in quotation marks. Also, to include 
quotation marks in your response, use two sets of quotation marks in the 
places you want quotation marks to appear. For example: 

$ INQUIRE FILE "Filename" 

Filename: "OZ""WITCH GLINDA""::[GLINDA]SPELLS.DAT" 

$ SHOW SYMBOL FILE 

FILE = "0Z"WITCH GLINDA"::[GLINDA]SPELLS.DAT" 

Usually when you include an access control string, you enclose the user name 
and password in quotation marks. However, when you provide the string in 
response to the INQUIRE command, you must enclose the user name and 
password in double quotation marks. 

You can also use the READ command to obtain data and retain the original 
case, spaces, and quotation marks. With the READ command, you do not 
have to enclose your response in quotation marks or use two sets of quotation 
marks to insert a quotation mark. For example: 

$ READ/PROMPT="Filename: " SYS$COMMAND FILE 
Filename: 0Z"witch glenda"::[glenda]spells.dat 
$ SHOW SYMBOL FILE 

FILE = "0Z"witch glenda"::[glenda]spells.dat" 

You may find it useful to write command procedures that can either accept 
parameters or prompt for user input if the required parameters are not 
specified. For example: 

$ ! Prompt for a file name if name 

$ ! is not passed as a parameter 

$ IF PI .EQS. "" THEN INQUIRE PI "Filename" 

$ COPY * PI’ DISK5:[RESERVED]*.* 

$ EXIT 

Note: If you submit a command procedure for execution as a batch job, DCL 

reads the value for a symbol specified in an INQUIRE command from the 
data line following the INQUIRE command. If you do not include a data 
line, DCL assigns the symbol a null value. 
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3.2 Passing Data to Commands and Images 

When you execute DCL commands that execute images supplied with your 
system or when you run your own images, you may need to provide input 
data. Images obtain input from SYS$INPUT, the default input stream. In 
a command procedure, SYS$INPUT is defined as the command procedure 
file. Therefore, if commands or images require input data, they will look in 
the command procedure file. However, you can redefine SYS$INPUT if you 
want to provide data from your terminal or from an input file. The following 
sections describe different methods of passing data to commands and images. 



3.2.1 Including Data in the Command Procedure 

Use data lines to include data for commands and images within the 
procedure. The following command procedure runs the image CENSUS.EXE, 
which requires input data. CENSUS.EXE obtains input from SYS$INPUT, the 
command procedure file. 

$! Execute CENSUS 
$ RUN CENSUS 

1981 

1982 

1983 

$ EXIT 

Note that the command procedure passes the text on a data line directly 
to CENSUS.EXE; DCL does not process the data lines. If you include DCL 
symbols or expressions on data lines, DCL will not substitute values for the 
symbols or evaluate the expressions. If you use an exclamation point in a 
data line, the image to which you pass the data processes the exclamation 
point. 

To include data lines that begin with dollar signs in the input stream, you 
must define the input data in a way that prevents the command interpreter 
from attempting to execute the data as a command. To delimit such an input 
stream, use the DECK and EOD (End of Deck) commands. For example: 

$ ! Everything between the commands DECK and EOD 
$ ! is written to the file WEATHER.COM 
$ ! 

$ CREATE WEATHER.COM 
$ DECK 

$ FORTRAN SUMMER 
$ LINK SUMMER 
$ RUN SUMMER 
$ EOD 
$ ! 

$ ! Now execute WEATHER.COM 
$ QWEATHER 
$ EXIT 

This command procedure creates and executes WEATHER.COM. Because the 
data lines begin with dollar signs, these lines are delimited by DECK and 
EOD. 
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You can also place programs in the command procedure file by specifying 
the name of the data file as SYS$INPUT. This causes the compiler to read 
the program from the command procedure, rather than from another file. 

The following example illustrates a command procedure that contains a 
FORTRAN command followed by the program's statements: 

$ FORTRAN/OBJECT=TESTER/LIST=TESTER SYS$INPUT 
C THIS IS A TEST PROGRAM 
A = 1 
B = 2 
STOP 
END 

$ PRINT TESTER.LIS 
$ EXIT 

In this example, the FORTRAN command uses the logical name SYS$INPUT 
to identify the file to be compiled. Because SYS$INPUT is equated to the 
command procedure, the FORTRAN compiler compiles the statements 
following the FORTRAN command (up to the next line that begins with 
a dollar sign). When the compilation completes, two output files are created: 
TESTER.OBJ and TESTER.LIS. The PRINT command then prints the listing 
file. 

Include data in the command procedure when you always pass the same data 
to the command or image you are running. However, if you want to pass 
different data without rewriting the command procedure, you can redefine 
SYS$INPUT to either your terminal or to a data file. The following sections 
describe these techniques. 


3.2.2 Supplying Data to an Image 

To run an image from a command procedure and supply data to the image 
interactively, redefine SYS$INPUT to be your terminal. After you redefine 
SYS$INPUT as your terminal, the image called from the command procedure 
obtains input from your terminal rather than from data lines in the command 
procedure. Use this method of obtaining input when you execute command 
procedures interactively. You cannot supply data interactively to batch mode 
command procedures. 

Use the following command to redefine SYS$INPUT as your terminal: 

$ DEFINE/USER.MODE SYS$INPUT SYS$COMMAND 

SYS$COMMAND is a logical name that is, by default, defined as your 
terminal when you are using the system interactively. 

When you redefine SYS$INPUT (or any other logical name for a process 
permanent file) you should use the /USER_MODE qualifier. The /USER_ 
MODE qualifier creates a temporary logical name assignment that is in effect 
only until the next image completes. 

For example, if you want to execute the image CENSUS.EXE but you want to 
provide the years interactively, you can include the following commands in 
your procedure: 

$ ! Execute CENSUS getting data from the terminal 
$ DEFINE/USER.MODE SYS$INPUT SYS$COMMAND 
$ RUN CENSUS 
$ EXIT 
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The DEFINE/USER_MODE command temporarily redefines SYS$INPUT 
while CENSUS.EXE is running, so CENSUS.EXE obtains its input from the 
terminal. After CENSUS.EXE completes, SYS$INPUT reverts to its original 
definition (the command procedure file.) 

To use any DCL command or utility that requires interactive input in a 
command procedure, you must redefine SYS$INPUT to be your terminal. For 
example, the next command procedure uses the EDT editor: 

$ ! Obtain a list of your files 
$ DIRECTORY 
$ ! 

$ ! Get file name and invoke the EDT editor 
$ EDIT.LOOP: 

$ INQUIRE FILE "File to edit (Press RET to end)" 

$ IF FILE .EQS. "" THEN EXIT 

$ DEFINE/USER_MODE SYS$INPUT SYS$COMMAND 

$ EDIT ’FILE’ 

$ GOTO EDIT.LOOP 

This command procedure prompts for file names until you terminate the loop 
by pressing the RETURN key. When you enter a file name, the procedure 
automatically invokes the EDT editor to edit the file. While the editor is 
running, SYS$INPUT is defined as the terminal so you can enter your edits 
interactively. 


3.2.3 Defining SYS$INPUT as a File 

You can also redefine SYS$INPUT to be a data file. For example, the 
following command procedure executes the image CENSUS.EXE, and the 
input data is provided in the file YEARS.DAT: 

$ !Execute CENSUS using data in YEARS.DAT 
$ DEFINE/USER_MODE SYSSINPUT YEARS.DAT 
$ RUN CENSUS 
$ EXIT 

If you redefine SYS$INPUT to be a file, you can change the data processed 
by the command procedure by editing the data file. 


3.3 Directing Output from Command Procedures 

Command procedures can direct output in the following ways: 

• Writing data to the default output file, or redirecting data to another file 

• Displaying error messages when certain types of errors occur 

• Returning values as global symbols or logical names 

• Displaying verification of command and data lines 

The following sections describe these methods of directing output. 
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3.3.1 Redirecting Output from Command Procedures 

In general, when you execute command procedures interactively, they display 
output at your terminal. This happens because command procedures send 
output to SYS$OUTPUT, which by default is defined as your terminal. Batch 
jobs send output to a batch job log file. See Chapter 8 for more information 
on batch job output. 

You can redirect output to a file by using the /OUTPUT qualifier when 
you execute a command procedure. In the following example, output from 
SETD.COM is written to the file RESULTS.TXT instead of to the terminal: 

$ @SETD/OUTPUT=RESULTS.TXT 

To determine the outcome of the command procedure, you can use the TYPE 
command to display the file RESULTS.TXT or the PRINT command to print 
it. 

Note: When you use the /OUTPUT qualifier, be sure to place it immediately 
after the command procedure file name, with no intervening spaces. 
Otherwise DCL interprets the qualifier as a parameter to be passed to the 
procedure. 

When you redirect command procedure output to a file, the procedure sends 
error messages to the terminal as well as to the file receiving the output. (See 
Section 3.3.3 for more information on controlling error messages.) 


3.3.2 Redirecting Output from Commands and Images 

To suppress or redirect output from an individual command or image, use the 
/OUTPUT qualifier with that command (if the command has an /OUTPUT 
qualifier) or redefine SYS$OUTPUT for the duration of the command's 
execution. 

For example, to trap the output from the DIRECTORY command, you can use 
the /OUTPUT qualifier. The output from the DIRECTORY command will be 
sent to the specified file while the output from other commands will still be 
sent to the terminal. For example: 

$ ! Trap the output from DIRECTORY in NUMBER.DAT 
$ ! Accumulate this information in GRAND_TOTAL.DAT 
$ 

$ DIRECTORY/TOTAL/OUTPUT=NUMBER.DAT 
$ APPEND/LOG NUMBER.DAT GRAND_TOTAL.DAT 
$ EXIT 

When you execute this procedure, do not use the /OUTPUT qualifier with 
the @ command because you want to redirect only the output from the 
DIRECTORY command. 

However, some commands do not have /OUTPUT qualifiers. To trap the 
output from such a command, temporarily redefine SYS$OUTPUT as a file. 
(SYS$OUTPUT is the logical name that commands and images generally use 
to determine where to send output.) You can also redefine SYS$OUTPUT to 
trap the output from a user-written program. 
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The following example shows how to redirect the output from the SHOW 
USERS command to a file. Because you used the /USER-MODE qualifier, 
the new definition for SYS$OUTPUT is in effect only for the execution of the 
SHOW USERS command. (The /USER-MODE qualifier creates a temporary 
logical name assignment that is in effect only until the next image completes.) 
Then, SYS$OUTPUT reverts to its default definition (the terminal). 

$ DEFINE/USER.MODE SYS$OUTPUT SHOW_USER.DAT 
$ SHOW USERS 
$ ! 

$ ! Process the information in SHOW_USER.DAT 
$ OPEN/READ INFILE SHOW_USER.DAT 
$ READ INFILE RECORD 


$ CLOSE INFILE 
$ EXIT 

To suppress output entirely from a command, temporarily define 
SYS$OUTPUT as a null device. For example: 

$ DEFINE/USER_MODE SYSSOUTPUT NL: 

$ APPEND NEW_DATA.DAT STATS.DAT 


You cannot use the DEFINE/USER—MODE command to redirect output 
from DCL commands that are executed within the command interpreter. 
Table 3-1 lists the commands that are executed within the command 
interpreter. Instead, you can redirect output from commands that are executed 
within the command interpreter by using the DEFINE command to redefine 
SYSSOUTPUT, and then using the DEASSIGN command to delete the 
definition when you are through with it. For example: 

$ DEFINE SYSSOUTPUT TIME.DAT 
$ SHOW TIME 
$ DEASSIGN SYSSOUTPUT 

After you deassign SYSSOUTPUT, its default value is restored. 

Table 3-1 Commands Performed Within the Command Interpreter 


= 

ALLOCATE 

ASSIGN 

ATTACH 

CALL 

CANCEL 

CLOSE 

CONNECT 

CONTINUE 

CREATE/LOGICAL_NAME_TABLE 

DEALLOCATE 

DEASSIGN 

DEBUG 

DECK 

DEFINE 

DEFINE/KEY 

DELETE/SYMBOL 

DISCONNECT 

ELSE 

ENDIF 

ENDSUBROUTINE 

EOD 

EXAMINE 

EXIT 

GOSUB 

GOTO 

IF 

INQUIRE 

ON 

OPEN 

READ 

RECALL 

RETURN 
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Table 3-1 (Cont.) Commands Performed Within the Command Interpreter 


SET CONTROL 
SET ON 

SET PROTECTION/DEFAULT 

SET VERIFY 

SHOW QUOTA 

SHOW TIME 

STOP 

WAIT 


SET DEFAULT 
SET OUTPUT_RATE 
SET UIC 

SHOW DEFAULT 
SHOW STATUS 


SUBROUTINE 

WRITE 


SHOW TRANSLATION SPAWN 


SET KEY 
SET PROMPT 
SET SYMBOL/SCOPE 
SHOW KEY 
SHOW SYMBOL 


THEN 


3.3.3 Redirecting Error Messages 


By default, command procedures send error messages to the file indicated 
by SYS$ERROR. You can redefine SYS$ERROR to direct error messages to 
a specified file. However, if you redefine SYS$ERROR to be different from 
SYS$OUTPUT (or if you redefine SYS$OUTPUT without also redefining 
SYS$ERROR), DCL commands and images using standard VMS error display 
mechanisms send error and severe error messages to both SYS$ERROR and 
SYS$OUTPUT. Therefore, you receive these messages twice—once in the file 
indicated by the definition of SYS$ERROR, and once in the file indicated by 
SYS$OUTPUT. Success, informational, and warning messages are sent only 
to the file indicated by SYS$OUTPUT. 

If you want to suppress error messages from a DCL command, be sure that 
neither SYS$ERROR nor SYS$OUTPUT is equated to the terminal. For 
example, the following command procedure accepts a directory name as a 
parameter, sets the default to that directory, and purges files in the directory. 
In order to suppress error messages, the procedure temporarily defines 
SYS$ERROR and SYS$OUTPUT as the null device. 

$ ! Purge files in a directory and suppress messages 
$ ! 

$ SET DEFAULT ’PI* 

$ ! Suppress messages 
$ ! 

$ DEFINE/USER.MODE SYS$ERR0R NL: 

$ DEFINE/USER.MODE SYS$OUTPUT NL: 

$ PURGE 
$ EXIT 

You can also use the SET MESSAGE command to suppress messages. For 
example: 
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$ ! Purge files in a directory and suppress messages 
$ ! 

$ SET DEFAULT ’PI’ 

$ ! Suppress messages 
$ ! 

$ SET MESSAGE/NOFACILITY - 

/NOIDENTIFICATION - 
/NOSEVERITY - 
/NOTEXT 

$ PURGE 

$ SET MESSAGE/FACILITY - 

/IDENTIFICATION - 

/SEVERITY 

/TEXT 

$ EXIT 

Note that if you run one of your own images from a command procedure 
and the image references SYS$ERROR, the image sends error messages 
only to the file indicated by SYS$ERROR—even if SYS$ERROR is different 
from SYS$OUTPUT. Only DCL commands and images using standard VMS 
error display mechanisms send error messages to both SYS$ERROR and 
SYS$OUTPUT when these files are different. 


3.3.4 Using Global Symbols to Return Data 

To return a value from a command procedure (either to a calling procedure 
or to DCL command level), you can assign the value to a global symbol 
because the global symbol can be read at any command level. You should 
use comments to explain the use of any global symbols. 

The following command procedure, AVERAGE.COM, computes the average 
of up to eight numbers that are passed as parameters: 

$ ! Find sum of the numbers (SUM) and 

$ ! determine how many numbers are being averaged (COUNT) 

$ ! 

$ IF PI .EQS. "" THEN GOTO ERR 
$ COUNT = 1 
$ SUM = 0 
$ LOOP: 

$ IF P’COUNT' .EQS. "" THEN GOTO DONE 
$ SUM = «tP'COUNT' + SUM 
$ COUNT = COUNT + 1 
$ GOTO LOOP 
$ ! 

$ ! Compute the average and store in the global symbol AVERAGE 
$ ! 

$ DONE: 

$ AVERAGE == SUM/(COUNT-1) 

$ EXIT 
$ ! 

$ ERR: 

$ WRITE SYS$OUTPUT "No numbers were provided." 

$ EXIT 

You can invoke AVERAGE.COM from another procedure, and then use the 
global symbol AVERAGE to indicate the average. For example: 
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$ 0AVERAGE 34 60 22 86 

$ WRITE SYS$0UTPUT "The average is ".AVERAGE 


3.3.5 Using Logical Names to Return Data 

You can also use logical names to return data from a nested command 
procedure to the calling procedure. When a logical name is defined, it 
is available at any command level. The following command procedure, 
REPORT.COM, obtains the file name for a report. Then the procedure 
defines the logical name REPORT-FILE, using the user-supplied name as the 
equivalence string. Finally, the procedure executes a program that writes a 
report to REPORT-FILE. 

$! Obtain the name of a file and then run 
$! REPORT.EXE to write a report to the file 
$! 

$ INQUIRE FILE "Name of report file" 

$ DEFINE/NOLOG REPORT.FILE ’FILE’ 

$ RUN REPORT 
$ EXIT 

If you invoke REPORT.COM from another procedure to create the report file, 
the calling procedure can use the logical name REPORT—FILE to refer to the 
report file. For example: 

$! Command procedure that updates data files 
$! and optionally prepares reports 
$! 

$ UPDATE: 


$ INQUIRE REPORT "Prepare a report [Y or N]" 

$ IF REPORT THEN GOTO REPORT.SEC 
$ EXIT 
$! 

$ REPORT_SEC: 

$ ®REPORT 

$ WRITE SYS$OUTPUT "Report written to ", F$TRNLNM("REPORT_FILE") 
$ EXIT 


3.3.6 Verifying Command Procedure Execution 

By default, only the output from commands and images is displayed when 
you execute command procedures interactively. If you also want to see 
the DCL command lines, data lines, and comment lines, use the SET 
VERIFY command. You can enter the SET VERIFY command either within 
the command procedure or at the interactive command level. If you set 
verification, the SET VERIFY command will be in effect for all subsequent 
command procedures you execute during the terminal session until you enter 
the SET NOVERIFY command. 


3-12 


For example, to display lines in a particular command procedure, place the 
SET VERIFY command at the beginning of the procedure and place the SET 
NOVERIFY command at the end: 







Command Procedure Input/Output 

3.3 Directing Output from Command Procedures 


$ ! Turn verification on 
$ ! 

$ SET VERIFY 
$ LOOP: 

$ INQUIRE FILE "File name" 

$ IF FILE .EQS."" THEN EXIT 

$ PRINT ’FILE’ 

$ GOTO LOOP 

$ ! Turn verification off 
$ ! 

$ SET NOVERIFY 

You can interrupt the interactive execution of a command procedure to turn 
verification on if that command procedure contains neither the SET VERIFY 
command nor a CTRL/Y handler. As shown in the following example, press 
CTRL/Y to interrupt execution, enter the SET VERIFY command, and enter 
the CONTINUE command to continue execution of the command procedure 
(with verification turned on.) 

$ OMASTER 

ICTRL/YI 

Interrupt 

$ SET VERIFY 
$ CONTINUE 

$ ! The next step in this procedure is to 


Verifying that a command procedure executes successfully is the principal 
debugging tool for detecting errors in a command procedure. If the SET 
NOVERIFY command is in effect and an error occurs, it may be difficult to 
determine which command caused the error. With the SET VERIFY command 
in effect, it is much easier to determine the cause of the error. 

You can use the SET VERIFY command with special keywords to indicate 
that only command lines or data lines are to be verified. See the VMS DCL 
Dictionary for more information on the SET VERIFY command. 

You can also use the F$VERIFY lexical function to change verification states. 
For example: 

$ ! Turn verification on 
$ ! 

$ TEMP = F$VERIFY(1) 

$ LOOP: 

$ INQUIRE FILE "File name" 

$ IF FILE .EQS."" THEN EXIT 

$ PRINT ’FILE’ 

$ GOTO LOOP 

$ ! Turn verification off 
$ ! 

$ TEMP = F$VERIFY(0) 

$ EXIT 

See Chapter 4 for information on how to save verification settings before you 
change them. 
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3.4 Writing Data to the Terminal 

There are several ways that you can write data to the terminal. The most 
common ways are with the WRITE command and the TYPE command, as 
described in the following sections. 


3.4.1 Using the WRITE Command 

When you execute a command procedure interactively, you can use the 
WRITE command to display lines at the terminal. To do this, specify the 
output file as SYS$OUTPUT. You must express the data you want to write 
as a string expression; the data can be a character string, a symbol, a lexical 
function, or a combination of these entities. 

The following example shows different ways you can use the WRITE 
command: 

$ ! The following line writes a character string 
$ WRITE SYSSOUTPUT "Two files were written." 

$ ! 

$ ! The following line writes a symbol 
$ FILE = "STAT1.DAT" 

$ WRITE SYS$OUTPUT FILE 
$ ! 

$ AFILE = "STAT1.DAT" 

$ BFILE = "STAT2.DAT" 

$ ! The following line writes a character string that 
$ ! contains a symbol 

$ WRITE SYSSOUTPUT "’’AFILE’ and ’’BFILE’ were written." 

$ ! 

$ ! The following line writes a list of items 
$ WRITE SYSSOUTPUT AFILE, " and ".BFILE," were written." 

$ EXIT 

To display a long line, continue the line over two lines. For example: 

$ ! writing a long line 

$ WRITE SYSSOUTPUT "REPORT BY MARY JONES" + - 
" PREPARED APRIL 15, 1984" 

$ EXIT 

To include quotation marks in a string you are writing, use two sets of 
quotation marks in the places you want quotes to appear. For example: 

$ ! including quotes 

$ WRITE SYSSOUTPUT "SUMMARY OF ”"Q AND A"" SESSION" 

$ EXIT 
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3.4.2 Using the TYPE Command 

Use the TYPE command to display text that is several lines long and does 
not require symbol substitution. The TYPE command writes data from the 
file you specify to SYS$OUTPUT. For interactive command procedures, 
SYS$INPUT is, by default, the file you are typing from. The TYPE command 
reads data from the data lines that follow and displays these lines on the 
terminal. For example: 

$ ! Using TYPE to display lines 
$ TYPE SYS$INPUT 
REPORT BY MARY JONES 
PREPARED APRIL 15, 1988 

SUBJECT: Analysis of Tax Deductions for 1987 


$ EXIT 

When you use the TYPE command to display data, DCL does not process 
the data lines. Therefore, DCL does not evaluate symbols, expressions, and 
lexical functions. Use the WRITE command to display data if you need to 
evaluate symbols, expressions, or lexical functions. 

You can also use the TYPE command to execute command procedures on a 
remote node. See Section 1.2.3 for instructions. 
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This chapter shows some types of information you can obtain and manipulate 
within a command procedure using lexical functions. It shows how to get 
information about 

• Your process 

• The system 

• Files and devices 

• Logical names 

• Strings 

• Data types 

This chapter gives general information for each lexical function; for complete 
descriptions, see the VMS DCL Dictionary. In addition. Appendix B lists each 
lexical function and its arguments. 

Many lexical functions return information that you can also get from DCL 
commands. You can manipulate information in a command procedure more 
easily if you obtain it from a lexical function, rather than from a command. 
For example, you can use either the F$ENVIRONMENT function or the 
SHOW DEFAULT command to obtain the name of your current default 
directory. If you use the F$ENVIRONMENT function, you can assign the 
result to a symbol, and then use this symbol later in the procedure, as 
follows: 

$ DIR.NAME = F$ENVIRONMENT("DEFAULT") 

$ SET DEFAULT DISK4:[TEST] 


$ SET DEFAULT ’DIR_NAME’ 

The F$ENVIRONMENT function returns the current default disk and 
directory, and stores this value in the symbol DIR_NAME. At the end of 
the procedure, you use the symbol DIR_NAME to restore the default with 
the SET DEFAULT command. 

If you obtain the value of the current default directory with the SHOW 
DEFAULT command, rather than the F$ENVIRONMENT lexical function, 
you cannot assign this output to a symbol. Instead, you must redirect the 
output of the SHOW DEFAULT command to a file. To reset the default 
directory, you must open the file containing the SHOW DEFAULT command 
output, read and parse the record containing the directory name, reset the 
directory, and close the file. Then, you must delete the file containing the 
SHOW DEFAULT output. 


4-1 









Using Lexical Functions 

4.1 Obtaining Information About Your Process 


4.1 


Obtaining Information About Your Process 

You can use the following lexical functions to obtain information about your 
process: 


F$DIRECTORY 

F$ENVIRONMENT 

F$GETJPI 

F$MODE 

F$PRIVILEGE 

FSPROCESS 

FSSETPRV 

F$USER 

F$VERIFY 


Returns the current default directory string. 

Returns information about the command environment for 
your process. 

Returns accounting, status, and identification information 
about your process, or about other processes on the 
system. 

Shows the mode in which your process is executing. 

Indicates whether your process has the specified 
privileges. 

Returns the name of your process. 

Sets the specified privileges. This function also indicates 
whether the specified privileges were previously enabled 
before you used the F$SETPRV function. 

Returns your user identification code. 

Indicates whether verification is on or off. 


You often change process characteristics for the duration of a command 
procedure, and then restore them. Table 4-1 shows process characteristics 
that are commonly changed in command procedures; it also gives the lexical 
functions that save these characteristics and the DCL commands that change 
and restore the original settings. 

Note that if you save process characteristics, you may need to ensure that 
an error or CTRL/Y interrupt does not cause the procedure to exit before 
restoring the original characteristics. See Chapter 7 for more information on 
handling errors and CTRL/Y interrupts. 


Table 4-1 Commonly Changed Process Characteristics 


Characteristic Operation Command/Lexical Function 


Control characters 

Save: 

Restore: 

F$ENVIRONMENT ("CONTROL”) 

SET CONTROL 

DCL prompt 

Save: 

Restore: 

F$ENVIRONMENT('PROMPT") 

SET PROMPT 

Default protection 

Save: 

Restore: 

F$EN VIRONMENT ("PROTECTION") 
SET PROTECTION/DEFAULT 

Key state 

Save: 

Restore: 

F$ENVIRONMENT("KEY_STATE") 

SET KEY 

Message format 
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Table 4—1 (Cont.) Commonly Changed Process Characteristics 


Characteristic 

Operation 

Command/Lexical Function 


Restore: 

SET MESSAGE 

Privileges 

Save: 

FSPRIVILEGE or F$SETPRV 


Restore: 

FSSETPRV or SET PROCESS/PRIVILEGES 

Verification 

Save: 

F$VERIFY or F$ENVIRONMENT 


Restore: 

FSVERIFY or SET VERIFY 


4.1.1 Changing Verification Settings 

It is a common technique to turn verification off for the duration of a 
command procedure. This prevents users from displaying a procedure's 
contents while executing the procedure. In command procedures, you can set 
or disable two types of verification: 

Procedure verification Displays each command line as it is being 

executed 

Image verification Displays each data line as it is being processed 

The SET [NO]VERIFY command and the F$VERIFY function turn both types 
of verification on or off unless you explicitly request that only one type of 
verification be changed. 

In general, you keep your procedure and image verification settings the 
same. That is, you will keep them both on or off. However, you do not have 
to keep them the same. Therefore, before you change these settings in a 
command procedure, you should save each verification setting separately. For 
example: 

$ ! Save each verification state 
$ ! Turn both states off 

$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE") 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 


$ ! Restore original verification states 
$ SAVE_VERIFY_IMAGE = F$VERIFY(SAVE_VERIFY_PROCEDURE,- 
SAVE_VERIFY_IMAGE) 

The F$ENVIRONMENT function returns the current image verification 
setting, and assigns this value to the symbol SAVE_VERIFY_IMAGE. Next, 
the F$VERIFY function returns the current procedure verification setting 
and assigns this value to the symbol SAVE_VERIFY_PROCEDURE. The 
F$VERIFY function also turns off both image and procedure verification. 

Note that you can use the F$ENVIRONMENT function to obtain the 
procedure verification setting, and then you can use the F$VERIFY function 
to turn verification off. However, it is shorter to use F$VERIFY to accomplish 
both tasks in one command line, as shown in the previous example. 
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At the end of the procedure, you use the F$VERIFY function to restore the 
original settings (specified by the symbols SAVE_VERIFY_PROCEDURE and 
SAVE_VERIFY_IMAGE.) 


4.1.2 Changing Default Protection 

You may want to change the default file protection within a command 
procedure. The following command procedure changes the default protection 
associated with files created while the procedure is executing. The procedure 
restores the original default file protection before terminating. 

$ SAVE_PR0T = F$ENVIRONMENT("PROTECTION") 

$ SET PROTECTION = (SYSTEM:RWED. OWNER:RWED, GROUP, WORLD)/DEFAULT 


$ SET PROTECTION^’SAVE.PROT’)/DEFAULT 
$ EXIT 

Note that the F$ENVIRONMENT function returns the default protection code 
using the syntax required by the SET PROTECTION command. This allows 
you to use the symbol SAVE-PROT with the SET PROTECTION command 
to restore the original default file protection. 


4.2 


Obtaining Information About the System 

You can use the following lexical functions to obtain information about the 
system: 


F$GETQUI 

F$GETSYI 

F$IDENTIFIER 

F$MESSAGE 

F$PID 

F$TIME 


Returns information about queues, batch and print 
jobs currently in those queues, form definitions, and 
characteristic definitions kept in the system job queue file. 

Returns information about your local system or about a 
node in your cluster (if your system is part of a cluster). 

Converts identifiers from named to numeric format, and 
vice versa. 

Returns the message text associated with a status code. 

Returns the process identification number for processes 
that you are allowed to examine. 

Returns the current date and time. 


The following sections describe how to obtain information about the system. 









Using Lexical Functions 

4.2 Obtaining Information About the System 


4.2.1 Determining Your Node Name 

If your system is part of a network or a cluster where you can log into many 
different nodes, you can set the DCL prompt to indicate which node you 
are currently using. To do this, include the F$GETSYI function in your 
login command procedure to determine the node name. Then use the SET 
PROMPT command to set a unique prompt for the node. For example: 

$ NODE = F$GETSYI("NODENAME") 

$ SET PROMPT = NODE’S " 


If you want to use only a portion of the node name in your prompt string, 
use the F$EXTRACT function to extract the appropriate characters. (See 
Section 4.5.2 for more information on extracting characters.) 


4.2.2 Obtaining Information About Queues 

You can use the F$GETQUI function to get many types of information about 
batch and print queues. You must have either READ access to the job or 
SYSPRV or OPER privilege to obtain information about jobs and files in 
queues. 

The following example shows how to determine if the batch queue VAX1_ 
BATCH is in a stopped state. The value returned is either TRUE or FALSE. If 
the queue is not stopped, the command procedure submits a job to the queue. 

$ QSTOPPED = F$GETQUI("DISPLAY_QUEUE". "QUEUE.STOPPED", "VAX1.BATCH") 

$ IF QSTOPPED THEN GOTO NOBATCH 
$ SUBMIT/QUEUE=VAX1_BATCH TEST.COM 
$ NOBATCH: 


4.2.3 Obtaining Information About Processes 

You can use the F$PID function to get the process identification number (PID) 
for all processes that you are allowed to examine. You can obtain PIDs for all 
processes on the system if you have WORLD privilege; you can obtain PIDs 
for all processes in your group if you have GROUP privilege. If you have 
neither GROUP nor WORLD privilege, you can obtain only the PID for your 
process. 

The following example shows how to obtain and display the PIDs for the 
processes you are allowed to examine. 
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$ ! Display the time when this procedure 
$ ! begins executing 
$ WRITE SYS$OUTPUT FSTIMEO 
$ ! 

$ CONTEXT = "" 

$ START: 

$ ! Obtain and display PIDs until 
$ ! F$PID returns a null string 
$ ! 

$ PID = F$PID(CONTEXT) 

$ IF PID .EQS. "" THEN EXIT 
$ WRITE SYS$OUTPUT "Pid — ”PID”' 

$ GOTO START 

In this example, the system uses the symbol CONTEXT to hold a pointer into 
the system list of PIDs. Each time through the loop, the system changes the 
pointer to locate the next PID in the list. The procedure exits after all PIDs 
have been displayed. 

After you obtain a PID, you can use the F$GETJPI function to obtain specific 
information about the process. For example, you can enhance the above 
procedure so that it displays the PID and the UIC for each process: 

$ CONTEXT = "" 

$ START: 

$ ! Obtain and display PIDs and UICs 
$ ! 

$ PID = F$PID(CONTEXT) 

$ IF PID .EQS. "" THEN EXIT 
$ UIC = F$GETJPI(PID,"UIC") 

$ WRITE SYS$OUTPUT "Pid — ”PID’ Uic— ”UIC’ " 

$ GOTO START 

Note that you can shorten this command procedure by including the 
F$GETJPI function within the WRITE command, as follows: 

$ CONTEXT = "" 

$ START: 

$ PID = F$PID(CONTEXT) 

$ IF PID .EQS. "" THEN EXIT 

$ WRITE SYS$OUTPUT "Pid — ”PID’ Uic --- ”F$GETJPI(PID, "UIC") ’" 

$ GOTO START 


4.3 Obtaining Information About Files and Devices 

You can use the following lexical functions to obtain information about files 
and devices: 

F$FILE_ATTRIBUTES Returns information about file attributes. 

FSGETDVI Returns information about a specified device. 

F$PARSE Parses a file specification and returns the requested 

field(s). 

FSSEARCH Searches a directory for a file. 

The following sections describe how to obtain some commonly used file 
information. 
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4.3.1 




Searching for a File in a Directory 

Before processing a file, a command procedure should use the F$SEARCH 
function to test whether the file exists. For example, the following command 
procedure uses F$PARSE to apply a device and directory string to the file 
STATS.DAT. Then the procedure uses the F$SEARCFI function to determine 
whether STATS.DAT is present in DISK3:[JONES.WORK], If it is, the 
command procedure processes the file. Otherwise, the command procedure 
prompts for another input file. 

$ FILE = F$PARSE("STATS.DAT","DISK3:[JONES.WORK]",,,"SYNTAX.ONLY") 

$ IF F$SEARCH(FILE) .EQS. "" THEN GOTO GET.FILE 
$ PROCESS.FILE: 


$ GET.FILE: 

$ INQUIRE FILE "File name" 

$ GOTO PROCESS.FILE 

After determining that a file exists, the procedure can use the F$PARSE or the 
F$FILE—ATTRIBUTES function to get additional information about the file. 
For example: 

$ IF F$SEARCH("STATS.DAT") .EQS. "" THEN GOTO GET.FILE 
$ PROCESS_FILE: 

$ NAME = F$PARSE("STATS.DAT",, "NAME") 


$ GET.FILE: 

$ INQUIRE FILE "File name" 
$ GOTO PROCESS.FILE 



4.3.2 



Deleting Old Versions of Files 

If a command procedure creates files that you do not need after the procedure 
terminates, delete or purge these files before you exit from the procedure. Use 
the PURGE command to delete all versions except the most recent one; use 
the DELETE command with a version number to delete a specific version of 
the file or with a wildcard character in the version field to delete all versions 
of the file. 

To avoid error messages when using the DELETE command within a 
command procedure, use the F$SEARCFI function to verify that a file exists 
before you try to delete it. For example, you can write a command procedure 
that creates a file named TEMP.DAT only if certain modules are executed. 
The following line issues the DELETE command only if TEMP.DAT exists: 

$ IF F$SEARCH("TEMP.DAT") .NES. "" THEN DELETE TEMP.DAT;* 
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4.4 


Translating Logical Names 

You can use the following lexical functions to translate logical names: 

F$LOGICAL Returns the equivalence string for a logical name. 

F$TRNLNM Returns either the equivalence string or the requested attributes 
for a logical name. 


Note: The F$TRNLNM function supersedes the F$LOGICAL function that 

was used in earlier versions of the VMS operating system. You should 
use F$TRNLNM (instead of F$LOGICAL) to ensure that your command 
procedure processes logical names using the current system techniques. 


In some situations, you may want to use logical names rather than symbols as 
variables in command procedures. Programs can access logical names more 
easily than they can access DCL symbols. Therefore, to pass information to 
a program that you run from a command procedure, obtain the information 
using a symbol. Then use the DEFINE command to equate the value of the 
symbol to a logical name. 


The following example tests whether the logical name NAMES has been 
defined. If it has, the procedure runs PAYROLL.EXE. Otherwise, the 
procedure obtains a value for the symbol FILE and uses this value to create 
the logical name NAMES. PAYROLL.EXE uses the logical name NAMES to 
refer to the file of employee names. For example: 


$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 


! Make sure that NAMES is defined 
IF F$TRNLNM("NAMES") .NES. "" THEN GOTO ALL.SET 
INQUIRE FILE "File with employee names" 

DEFINE NAMES ’FILE’ 


! Run PAYROLL, using the file indicated by NAMES 
ALL.SET: 

RUN PAYROLL 


You can also use the F$TRNLNM function to assign the value of a logical 
name to a symbol. For example: 


$ DEFINE NAMES DISK4:[JONESlEMPLOYEE_NAMES.DAT 
$ RUN PAYROLL 


$ FILE = F$TRNLNM(NAMES) 

$ WRITE SYS$OUTPUT "Finished processing ".FILE 


This command procedure defines a logical name that is used in the program 
PAYROLL. At the end of the procedure, the WRITE command displays 
a message indicating that the file was processed. Because the WRITE 
command does not translate logical names, you need to equate the logical 
name (NAMES) to a symbol (FILE). Then you can use the symbol FILE to 
display the file name. 
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4.5 


Manipulating Strings 


You can use the following lexical functions to manipulate character strings: 


F$CVTIME 

F$EDIT 

F$ELEMENT 

F$EXTRACT 

F$FAO 

F$LENGTH 

FSLOCATE 


Returns information about a time string. 

Edits a character string. 

Extracts an element from a string in which the elements are 
separated by delimiters. 

Extracts a section of a character string. 

Formats an output string. 

Determines the length of a string. 

Locates a character or a substring within a string and returns the 
offset. 


4.5.1 Determining if a String or Character is Present 

One common reason for examining strings is to determine whether a character 
(or substring) is present within a character string. To do this, use the 
F$LENGTH and the F$LOCATE functions. If the value returned by the 
F$LOCATE function equals the value returned by the F$LENGTH function, 
then the character you are looking for is not present. 

The following procedure requires a file name that includes the version 
number. To determine whether a version number is present, the procedure 
tests whether a semicolon (which precedes a version number in a file name) 
is included in the file name that the user enters: 

$ INQUIRE FILE "Enter file (include version number)" 

$ IF F$L0CATE(";", FILE) .EQ. F$LENGTH(FILE) THEN - 
GOTO NO.VERSION 


The F$LOCATE function returns the offset for the semicolon. Offsets start 
with 0; thus, if the semicolon were the first character in the string, the 
F$LOCATE function would return the integer 0. If the semicolon is not 
present within the string, the F$LOCATE function returns an offset that is 
one more than the offset of the last character in the string. This value is the 
same as the length returned by F$LENGTH, which measures the length of 
the string starting with the number 1. 


4.5.2 Extracting Part of a String 

To extract a portion of a string, use either the F$EXTRACT function or the 
F$ELEMENT function. Use the F$EXTRACT function to extract a substring 
that starts at a defined offset; use the F$ELEMENT function to extract part of 
a string between two delimiters. In order to use either of these functions, you 
must know the general format of the string you are parsing. 

Note: You do not need to use F$EXTRACT or F$ELEMENT to parse file 

specifications or time strings. Instead, use F$PARSE or F$CVTIME to 
extract the desired portion of these strings. 
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The following command procedure uses the F$EXTRACT function to extract 
the group portion of the UIC. This allows the procedure to execute a different 
set of commands depending on the user's UIC group. 

$ UIC = F$USER() 

$ GROUP.LEN = F$L0CATE(".",UIC) - 1 
$ GROUP = F$EXTRACT(1,GR0UP_LEN. UIC) 

$ GOTO ’GROUP’.SECTION 


$ WRITERS.SECTION: 


$ MANAGERS.SECTION: 


First, the procedure determines the UIC with the F$USER function. Next, 
the procedure determines the length of the group name by using F$LOCATE 
to locate the offset of the comma. The comma separates the group from the 
user portion of a UIC. Everything between the left bracket and the comma 
is part of the group name. For example, the group name from the UIC 
[WRITERS,SMITH] is WRITERS. 

After determining the length, the procedure extracts the name of the group 
with the F$EXTRACT function. The name starts with offset 1, and ends with 
the character before the comma. Finally, the procedure directs execution to 
the appropriate label. 

Note that you can determine the length of the group name at the same time 
you extract it. For example: 

$ UIC = F$USER() 

$ GROUP = F$EXTRACT(1, F$L0CATE(",".UIC) - 1. UIC) 

$ GOTO ’GROUP’.SECTION 

If a string contains a delimiter that separates different parts of the string, use 
the F$ELEMENT function to extract the part that you want. For example, in a 
protection code, each type of access is separated by a comma. For example: 

$ PROT = F$ENVIRONMENT("PROTECTION") 

$ SHOW SYMBOL PROT 

PROT = "SYSTEM=RWED, OWNER=RWED, GR0UP=RE, WORLD" 

Thus, you can use F$ELEMENT to obtain different types of access by 
extracting the portions of the string between the commas. To determine 
SYSTEM access, obtain the first element; to determine OWNER access, obtain 
the second element, and so on. 

The following example extracts the world access portion (the fourth element) 
from your default protection code. Note that when you use the F$ELEMENT 
function, element numbers start with zero. For this reason, use the integer 3 
to specify the fourth element. For example: 

$ PROT = F$ENVIRONMENT("PROTECTION”) 

$ WORLD.PROT = F$ELEMENT(3,",",PROT) 
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In this example, the F$ELEMENT function returns everything between the 
third comma and the end of the string. Thus, if your default protection 
allowed read access for world users, the string " WORLD=R" would be 
returned. 

After you obtain the world access string, you may need to examine it further. 
For example: 

$ PROT = F$ENVIRONMENT("PROTECTION") 

$ W0RLD_PR0T = F$ELEMENT(3.",".PROT) 

$ IF F$L0CATE("=", WORLD.PROT) .EQ. F$LENGTH(WORLD_PROT) - 
THEN GOTO N0_W0RLD_ACCESS 


4.5.3 Formatting Output Strings 

You can use the WRITE command to write a string to a record. For example, 
the following command procedure uses the WRITE command to display the 
process name and process identification number for processes on the system. 

$ ! Initialize context symbol to get PIDs 
$ CONTEXT = "" 

$ ! Write headings 

$ WRITE SYS$OUTPUT "Process Name PID" 

$ ! 

$ GET.PID: 

$ PID = F$PID(CONTEXT) 

$ IF PID .EQS. "" THEN EXIT 

$ WRITE SYS$OUTPUT F$GETJPI(PID."PRCNAM")," ", F$GETJPI(PID,"PID") 

$ GOTO GET.PID 

Note that the output from the WRITE command inserts five spaces between 
the process name and and the user name, but the columns do not line up. 
For example: 

Process Name PID 
MARCHESAND 2CA0049C 

TRACTMEN 2CA0043A 

FALLON 2CA0043C 

ODONNELL 2CA00453 

PERRIN 2CA004DE 

CHAMPIONS 2CA004E3 

To line up the columns, you can use the F$FAO function to define record 
fields and place the process name and user name in these fields. When 
you use the F$FAO function, use a control string to define the fields in the 
record; then specify the values to be placed in these fields. For example, the 
following procedure uses the F$FAO function to define a 16 character field 
and a 12 character field. The F$FAO function places the process name in the 
first field, skips a space, and then places the PID in the second field. 
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$ ! Initialize context symbol to get PIDh 
$ CONTEXT = "" 

$ ! Write headings 

$ WRITE SYSSOUTPUT "Process Name PID" 

$ ! 

$ GETJPID: 

$ PID = F$PID(CONTEXT) 

$ IF PID .EQS. "" THEN EXIT 

$ LINE = F$FA0("!16AS !12AS". FSGETJPI(PID,"PRCNAM"), F$GETJPI(PID,"PID")) 
$ WRITE SYS$OUTPUT LINE 
$ GOTO GET.PID 

Now when you execute the procedure, the columns will be correctly 
formatted: 


Process Name PID 

MARCHESAND 2CA0049C 

TRACTMEN 2CA0043A 

FALLON 2CA0043C 

ODONNELL 2CA00453 

PERRIN 2CA004DE 

CHAMPIONS 2CA004E3 

Another way to format fields in a record is to use a character string overlay. 
The following example uses an overlay to place the process name in the first 
16 characters (starting at offset 0) of the symbol RECORD. Then the PID is 
placed in the next 12 characters (starting at offset 17): 

$ ! Initialize context symbol to get PIDs 
$ CONTEXT = "" 

$ ! Write headings 

$ WRITE SYS$OUTPUT "Process Name PID" 

$ ! 

$ GET.PID: 

$ PID = F$PID(CONTEXT) 

$ IF PID .EQS. "" THEN EXIT 
$ RECORD[0.16]:= ’F$GETJPI(PID."PRCNAM")’ 

$ RECORD[17.12]:= ’F$GETJPI(PID."PID")’ 

$ WRITE SYS$0UTPUT RECORD 
$ GOTO GET_PID 

This procedure produces the same type of formatted columns you created 
with the F$FAO function: 


Process Name PID 

MARCHESAND 2CA0049C 

TRACTMEN 2CA0043A 

FALLON 2CA0043C 

ODONNELL 2CA00453 

PERRIN 2CA004DE 

CHAMPIONS 2CA004E3 


Note, however, that the F$FAO function is more powerful than a character 
string overlay; you can perform a wider range of output operations with the 
F$FAO function. 
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4.6 


Manipulating Data Types 

You can use the following lexical functions to convert data from strings to 
integers, and from integers to strings: 


F$CVSI 

F$CVUI 

F$INTEGER 

F$STRING 

FSTYPE 


Extracts bit fields from a character string and converts the result, 
as a signed value, to an integer. 

Extracts bit fields from a character string and converts the result, 
as an unsigned value, to an integer. 

Converts a string expression to an integer. 

Converts an integer expression to a string. 

Determines the data type of a symbol. 


4.6.1 Converting Data Types 

Use the F$INTEGER and F$STRING functions to convert between integers 
and strings. For example, the following command procedure converts data 
types. If you enter a string, the command procedure shows the integer 
equivalent. If you enter an integer, the command procedure shows the string 
equivalent. Note how the F$TYPE function is used to form a label name in 
the GOTO statement; F$TYPE returns "STRING" or "INTEGER" depending 
on the data type of the symbol. 

$ IF PI .EQS. "" THEN INQUIRE PI "Value to be converted" 

$ GOTO CONVERT.’F$TYPE(PI)’ 

$ 

$ CONVERT.STRING: 

$ WRITE SYS$OUTPUT "The string ”P1’ is converted to ”F$INTEGER(P1) ’" 

$ EXIT 
$ 

$ CONVERT.INTEGER: 

$ WRITE SYS$OUTPUT "The integer ”P1’ is converted to ’’F$STRING(P1) ’" 

$ EXIT 


4.6.2 Evaluating Expressions 

Some commands, such as INQUIRE and READ, accept only string data. If 
you use these commands to obtain data that you want to evaluate as an 
integer expression, use the F$INTEGER function to convert and evaluate this 
data. For example: 

$ INQUIRE EXP "Enter integer expression" 

$ RES = F$INTEGER(’EXP’) 

$ WRITE SYS$OUTPUT "Result is".RES 

The following example shows sample output from this command procedure: 

Enter integer expression: 9+7 
Result is 16 

Note that you must place apostrophes around the symbol EXP when you use 
it as an argument for the F$INTEGER function. This causes DCL to substitute 
the value for EXP during the first phase of symbol substitution. In the above 
example, the value "9 + 7" is substituted. When the F$INTEGER function 
processes the argument "9 + 7", it evaluates the expression and returns the 
correct result. 
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4.6.3 Determining Whether a Symbol Exists 

Use the F$TYPE function to determine whether a symbol exists; the F$TYPE 
function returns a null string if a symbol is undefined. For example: 


$ IF F$TYPE(TEMP) .EQS. "" THEN TEMP = "YES" 
$ IF TEMP .EQS. "YES" THEN GOTO TEMP_SEC 


This procedure tests whether the symbol TEMP has been previously defined. 
If it has, then the current value of TEMP is retained. If TEMP is not defined, 
then the IF statement assigns the value "YES" to TEMP. 
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The normal flow of execution in a command procedure is sequential: the 
commands in the procedure execute, in order, until the end of the file is 
reached. However, in many cases you will want to control whether certain 
statements are executed or the conditions under which the procedure should 
continue executing. 

This chapter discusses the commands that you can use in a command 
procedure to control or alter the flow of execution: 

• The CALL command transfers control to a labeled subroutine in a 
command procedure and creates a new command level. 

• The IF command tests the value of an expression and executes a 
command or block of commands following the THEN command if 

the result of the expression is true. If the result of the expression is false 
and the ELSE command is specified, the command or block of commands 
following the ELSE command execute. 

• The GOSUB command transfers control to a labeled subroutine in a 
command procedure but does not create a new command level. 

• The GOTO command transfers control to a labeled line in the procedure. 

• The Execute Procedure command (@) invokes (or calls) another 
command procedure and creates another command level. 

• The EXIT command terminates the current procedure and returns control 
to the previous command level. 

• The STOP command terminates the current procedure and returns to 
command level 0. 


Design 

Before writing a command procedure, analyze the tasks you want to perform. 
You may find it helpful to perform the tasks interactively to identify the steps 
involved in performing the tasks. In particular, look for the following: 

Variables Data that change each time you perform the task 

Conditionals Conditions that must be tested each time you perform the 

task 

Iterations Groups of commands that are performed repetitively until a 

condition is met 

For example, you decide to write a command procedure to clean up a 
directory. Before you start, you clean up one of your directories interactively 
and notice that you do the following: 

• Enter the DIRECTORY command to see what files are in the directory 

• Enter the PURGE command to delete old versions of files 
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• Enter the TYPE command to display the contents of a file before you 
decide whether to delete it 

• Enter the PRINT command to print a hard copy of a file before you delete 
it 

• Enter the DELETE command to delete files you no longer want to keep 

After determining the commands you use to clean a directory, you identify 
the following variables: the command to be executed and the file to be 
processed. These variables change each time you perform the procedure. 

Next, you identify the following conditionals. First, you need to determine 
which command to perform. If the requested command is not one of the 
commands that the procedure performs, you need to output an error message 
and get another command. Also, you need to determine when to terminate 
the procedure. 

Finally, you decide that the command procedure will repeat the following 
sequence of commands until the directory is clean: obtain a command, see 
if you are done, perform the command if the command is valid, and obtain 
another command. 


5.2 Coding 

To make the command procedure easier to understand and maintain, try to 
write the statements so that the procedure executes straight through from the 
first command to the last command. This section shows the steps you use to 
code a command procedure to clean up a directory. This example command 
procedure used in this section is called CLEAN.COM. 


5.2.1 Obtaining Variables 

First, decide how to obtain the values for your variables. You can use 
any of the methods for obtaining input described in Chapter 3. However, 
one of the most common methods for obtaining values for variables is 
to use the INQUIRE command to equate the values to symbols. In this 
command procedure, the procedure obtains the command from the user who 
is executing the procedure and equates the value to the symbol COMMAND: 

$ INQUIRE COMMAND - 

"Enter command (DELETE, DIRECTORY, PRINT, PURGE, TYPE)" 


5.2.2 Coding the General Design 

According to your design, the first thing you want to do after you obtain a 
command is to see whether you are through, or whether you need to perform 
the command. To do this, you decide to add an EXIT command so you can 
test whether the user entered "EXIT". For example: 

$ INQUIRE COMMAND - 

"Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)" 

$ IF COMMAND .EQS. "EXIT" THEN EXIT 
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Next, you need to determine which command to execute. To do this, check 
the command entered by the user against each possible command. If you 
find a match, execute the command. If you do not find a match, go on to the 
next command. If there is no match after you have checked for each valid 
command, output an error message. 

To test whether a condition is true, use the IF...THEN commands. To change 
the flow of execution, use the GOTO command to direct the flow of execution 
to a label in the command procedure. Also, use program stubs as placeholders 
for the code that performs each command. A stub is a temporary section of 
code that you use in your procedure while you test the design. Usually, a 
program stub outputs a message stating the function it is replacing. After the 
overall design works correctly, replace each stub with the correct code. For 
example: 

$ INQUIRE COMMAND - 

"Enter command (DELETE. DIRECTORY. EXIT, PRINT. PURGE, TYPE)" 

$ IF COMMAND .EQS. "EXIT" THEN EXIT 

$! 

$!Execute if user entered DELETE 
$ DELETE: 

$ IF COMMAND .NES. "DELETE" THEN GOTO DIRECTORY 

$ WRITE SYS$OUTPUT "This is the DELETE section." 

$! 

$!Execute if user entered DIRECTORY 
$ DIRECTORY: 

$ IF COMMAND .NES. "DIRECTORY" THEN GOTO PRINT 

$ WRITE SYS$OUTPUT "This is the DIRECTORY section." 

$! 

$!Execute if user entered PRINT 
$ PRINT: 

$ IF COMMAND .NES. "PRINT" THEN GOTO PURGE 

$ WRITE SYSSOUTPUT "This is the PRINT section." 


$!Execute if user entered PURGE 
$ PURGE: 

$ IF COMMAND .NES. "PURGE" THEN GOTO TYPE 

$ WRITE SYSSOUTPUT "This is the PURGE section." 

$! 

$!Execute if user entered TYPE 
$ TYPE: 

$ IF COMMAND .NES. "TYPE" THEN GOTO ERROR 

$ WRITE SYSSOUTPUT "This is the TYPE section." 

$! 

$ ERROR: 

$ WRITE SYS$OUTPUT "You entered an invalid command." 

$ 

$ EXIT 

Now that you have the lines that test your conditionals, finish the design by 
adding the loop that allows you to obtain a command, process the command, 
and repeat the process until the user enters the EXIT command. To do this, 
direct the flow of execution back to the beginning of the procedure after the 
procedure executes a command. Leave the loop only when the user enters 
the EXIT command. For example: 
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$ GET.COMMAND.LOOP: 

$ INQUIRE COMMAND - 

"Enter command (DELETE. DIRECTORY. EXIT, PRINT, PURGE, TYPE)" 

$ IF COMMAND .EQS. "EXIT" THEN GOTO END.LOOP 

$! 

$!Execute if user entered DELETE 
$ DELETE: 

$ IF COMMAND .NES. "DELETE" THEN GOTO DIRECTORY 

$ WRITE SYS$OUTPUT "This is the DELETE section." 

$ GOTO GET_COMMAND_LOOP 

$! 

$!Execute if user entered DIRECTORY 
$ DIRECTORY: 

$ IF COMMAND .NES. "DIRECTORY" THEN GOTO PRINT 

$ WRITE SYSSOUTPUT "This is the DIRECTORY section." 

$ GOTO GET_COMMAND_LOOP 

$! 

$!Execute if user entered PRINT 
$ PRINT: 

$ IF COMMAND .NES. "PRINT" THEN GOTO PURGE 

$ WRITE SYSSOUTPUT "This is the PRINT section." 

$ GOTO GET.COMMAND.LOOP 

$! 

$!Execute if user entered PURGE 
$ PURGE: 

$ IF COMMAND .NES. "PURGE" THEN GOTO TYPE 

$ WRITE SYSSOUTPUT "This is the PURGE section." 

$ GOTO GET.COMMAND.LOOP 

$! 

$!Execute if user entered TYPE 
$ TYPE: 

$ IF COMMAND .NES. "TYPE" THEN GOTO ERROR 

$ WRITE SYSSOUTPUT "This is the TYPE section." 

$ GOTO GET.COMMAND.LOOP 

$! 

$ ERROR: 

$ WRITE SYSSOUTPUT "You entered an invalid command." 

$ GOTO GET.COMMAND.LOOP 

$• 

$ END.LOOP: 

$ WRITE SYSSOUTPUT "Directory ”F$DIRECTORY() ’ has been cleaned." 
$ EXIT 


5.2.3 Testing and Debugging 

Once you have written the code using program stubs, test the overall logic 
of the command procedure. Test all possible paths of execution. To test 
CLEAN.COM, enter each valid command, enter an invalid command, and 
exit using the EXIT command. For example: 

$ 0CLEAN 

Enter command (DELETE, DIRECTORY. EXIT, PRINT, PURGE, TYPE): DELETE 
This is the DELETE section. 


Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE): EXIT 
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Use the SET VERIFY and SHOW SYMBOL commands to help debug 
command procedures. When verification is set, you can see errors and the 
lines that generate them. For example, the following section of CLEAN.COM 
contains a spelling error. You can determine where the error occurs by 
turning verification on before you execute the procedure. 

$ SET VERIFY 
$ 0CLEAN 

$ GET_COMMAND_LOOP: 

$ INQUIRE COMMAND - 

"Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)" 

Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE): EXIT 
$ IF COMMAND .EQS. "EXIT" THEN GOTO END.LOP 

^DCL-W-USGOTO, target of GOTO not found - check spelling and presence of label 

The label END—LOP is spelled incorrectly. To correct the error, change the 
label to END_LOOP. 

The next example uses the SHOW SYMBOL command to determine how the 
symbol COMMAND is defined. 


$ SET VERIFY 
$ ©CLEAN 

$ GET_COMMAND_LOOP: 

$ INQUIRE COMMAND - 

"ENTER COMMAND (DELETE, DIRECTORY. EXIT, PRINT, PURGE, TYPE)" 
ENTER COMMAND (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE): EXIT 
$ SHOW SYMBOL COMMAND 
COMMAND = "EXIT" 

$ IF COMMAND .EQS. "exit" THEN GOTO END.LOOP 


In this example, the SHOW SYMBOL command shows that the symbol 
COMMAND has the value "EXIT". (The INQUIRE command automatically 
converts input to uppercase.) The IF statement that tests the command uses 
lowercase characters in the string "exit", so DCL determines that the strings 
are not equal. To correct the error, make sure the quoted string in the IF 
statement is written in capital letters; the rest of the string can use either 
uppercase or lowercase. For example: 

$ if command .eqs. "EXIT" then goto end_loop 


5.2.4 Filling in the Program Stubs 

When your general design works correctly, complete the command procedure 
by substituting commands for the program stubs. After you replace a stub 
with commands, test it to make sure the procedure works correctly. For a 
complicated task, it might be helpful to test the commands before adding 
them to the procedure. 

The following example shows the code for the TYPE section of CLEAN.COM: 

$! Execute if user entered TYPE 
$ TYPE: 

$ IF COMMAND ,NES. "TYPE" THEN GOTO ERROR 

$ INQUIRE FILE "File to type" 

$ TYPE ’FILE’ 

$ GOTO GET_COMMAND_LOOP 
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5.3 Techniques for Controlling Execution Flow 

The previous section illustrated some techniques you can use when designing 
procedures and directing the flow of execution. This section describes these 
techniques in more detail. 


5.3.1 IF Command 

The IF command tests the value of an expression and executes a command or 
block of commands when the result of the expression is true. When the result 
of the expression is false, one of the following occurs: 

• When one command follows the THEN command, it is not executed and 
the following command executes. 

• When a block of commands follows the THEN command, and the ELSE 
command is not specified, the command immediately following the 
ENDIF command executes. 

• When the ELSE command is specified, the command or block of 
commands following the ELSE command executes. 

The IF command can have one of the three following formats. The first 
format executes a single command when the expression specified to the IF 
command is true. 

$ IF expression THEN [$] command 

The second format executes a block of commands when the expression 
specified to the IF command is true. 

$ IF expression 
$ THEN 
$ command 

$ command 


$ ENDIF 

The third format executes one or more commands when the expression 
specified to the IF command is true, and executes one or more commands 
when the condition is false. 

$ IF expression 
$ THEN 
$ command 

$ command 


$ ELSE 
$ command 

$ command 


$ ENDIF 
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Note the following restrictions when using the IF-THEN-ELSE language 
construct: 

• IF statements can be nested to 16 levels. 

• A command block started by a THEN statement must be terminated by 
either an ELSE or an ENDIF statement. 

• A command block started by an ELSE statement must be terminated by 
an ENDIF statement. 

• A THEN statement must be the first executable statement following an IF 
statement. 

• You cannot specify a label on a line containing a THEN or an ELSE 
statement. You can, however, specify a label on a line containing an 
ENDIF statement. Programs may branch within the current command 
block, but branching into the middle of another command block is not 
recommended. 

The expression following the IF command can consist of one or more numeric 
constants, string literals, symbolic names, or lexical functions separated by 
logical, arithmetic, or string operators. An expression is true when it has one 
of the following values: 

• An odd integer value 

• A character string value that begins with any of the letters Y, y, T, or t 

• A character string value that contains numbers that form an integer with 
an odd value (for example, the string "27") 

An expression is false when it has one of the following values: 

• An even integer value 

• A character string value that begins with any letter other than Y, y, T, or 
t 

• A character string value that contains numbers that form an integer with 
an even value (for example, the string "28") 

When you write an expression for an IF command, follow the rules for writing 
expressions given in Chapter 2. (These rules are explained in more detail in 
the VMS DCL Concepts Manual.) In particular, remember the following: 

• When you use symbols in IF statements, their values are automatically 
substituted. Do not use apostrophes as substitution operators unless you 
need to force iterative translation. 

• String comparison operators end in the letter "S". For example, use 
operators such as .EQS., .LTS., and .GTS. to compare strings. By contrast, 
the operators .EQ., .LT., and .GT. are used for comparing integers. 

• When you test to see whether two strings are equal, the strings must 
use the same case in order for DCL to find a match. That is, the string 
"COPY" does not equal the string "copy" or the string "CoPy". 
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The following examples illustrate expressions that can be used with the IF 
command. For additional examples, see the description of the IF command 
in the VMS DCL Dictionary. The first example uses a logical operator and 
executes only one command following the THEN statement. 

$ INQUIRE CONT "Do you want to continue [Y/N]" 

$ IF .NOT. CONT THEN EXIT 


In this example, when the symbol CONT is not true, the procedure exits. 

The next example uses a symbol and a label within the IF expression: 

$ INQUIRE CHANGE "Do you want to change the record [Y/N]" 

$ IF CHANGE THEN GOTO GET.CHANGE 

$ GET.CHANGE: 


In this example, when the symbol CHANGE is true, the procedure transfers 
control to the label GET—CHANGE. Otherwise the procedure executes the 
command following the IF command. 

The next example illustrates two different IF commands. The first IF 
command compares two integers; the second IF command compares two 
strings. Note that the .EQ. operator is used for the integer comparison and 
the .EQS. operator is used for the string comparison. 

$ COUNT = 0 
$ LOOP: 

$ COUNT = COUNT + 1 
$ IF COUNT .EQ. 9 THEN EXIT 
$ IF P’COUNT’ .EQS. "" THEN EXIT 


$ GOTO LOOP 

First, the value of COUNT is compared to the integer 9; when the values are 
equal, then the procedure exits. When the values are not equal, the procedure 
continues. The loop terminates after eight parameters (the maximum number 
allowed) have been processed. 

In the second IF command, the string value of the symbol P'COUNT' is 
compared to a null string to see whether the symbol is undefined. Note 
that you must use apostrophes to force iterative substitution of the symbol 
COUNT. For example, when COUNT is 2, the result of the first translation is 
P2. Then, the value of P2 is used in the string comparison. 

You can execute a block of commands after the THEN command when 
the result of the IF expression is true. When using a block of commands, 
place the THEN command as the first command on the line following the IF 
command. In the following example, two SET TERMINAL commands execute 
and the procedure transfers control to the label PROCEED when F$MODE 
equals "INTERACTIVE". When F$MODE does not equal "INTERACTIVE", 
the procedure exits. 
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$ IF FSMODE () .EQS. "INTERACTIVE" 

$ THEN 

$ SET TERMINAL/DEVICE=VT200 

$ SET TERMINAL/WIDTH=132 

$ GOTO PROCEED 
$ ENDIF 
$ EXIT 
SPROCEED: 

The following example illustrates how to use a block of commands with the 
IF command in conjunction with the ELSE command. When the condition 
is true, the procedure writes a message to SYS$OUTPUT and executes the 
SHOW DEVICE and SET DEVICE commands. When the condition is not 
true, the procedure writes two messages to SYS$OUTPUT. 

$ INQUIRE DEV "Device to check" 

$ IF F$GETDVI(DEV, "EXISTS") 

$ THEN 

$ WRITE SYS$OUTPUT "The device exists." 

$ SHOW DEVICE ’DEV’ 

$ SET DEVICE/ERROR.LOGGING ’DEV’ 

$ ELSE 

$ WRITE SYS$OUTPUT "The device does not exist." 

$ WRITE SYS$OUTPUT "Error logging has not been enabled." 

$ ENDIF 
$ EXIT 

You can also execute a separate command procedure when the result of the IF 
expression is true. The following example executes the command procedure 
EXIT_ROUTINE.COM when the result of the IF expression is true: 

$ GET_COMMAND_LOOP: 

$ INQUIRE COMMAND - 

"Enter command (COPY, DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)" 

$ IF COMMAND .EQS. "EXIT" THEN (SEXIT.ROUTINE 


5.3.2 GOTO Command 

The GOTO command passes control to a labeled line in a command 
procedure. You can precede any command string in a command procedure 
with a label. The rules for entering labels are as follows: 

• A label must appear as the first item on a line after the dollar sign. 

• A label can have up to 255 characters. 

• A label can contain no embedded space characters. 

• A label must be terminated with a colon. 

For example: 

$ GOTO BYPASS 

$ BYPASS: 
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As the command interpreter encounters labels, it enters them in a special 
section of the local symbol table. The amount of space available for labels 
is limited. If a command procedure uses many symbols and contains many 
labels, the command interpreter may run out of symbol table space and issue 
an error message. If this occurs, include the DELETE/SYMBOL command in 
your procedure to delete symbols as they are no longer needed. 

If a command procedure uses the same label more than once, the new 
definition replaces the existing one in the local symbol table. When duplicate 
labels exist, the GOTO command transfers control to the label that DCL has 
processed most recently. The GOTO command uses the following rules when 
processing duplicate labels: 

• If duplicate labels all precede the GOTO command, control transfers to 
the label nearest the GOTO command. 

• If duplicate labels precede and follow the GOTO command, control 
transfers to the preceding label nearest the GOTO command. 

• If duplicate labels all follow the GOTO command, control transfers to the 
label nearest the GOTO command. 

The GOTO command is especially useful within a THEN clause to cause 
a procedure to branch forward or backward. For example, when you use 
parameters in a command procedure, you can test the parameters at the 
beginning of the procedure and branch to the appropriate label: 

$ IF PI .NES. "" THEN GOTO OKAY 
$ INQUIRE PI "Enter file spec" 

$ OKAY: 

$ PRINT/C0PIES=10 ’PI* 


In this example, the IF command checks that PI is not a null string. If PI 
is a null string, the GOTO command is not executed and the INQUIRE 
command prompts for a parameter value. Otherwise, the GOTO command 
causes a branch around the INQUIRE command. In either case, the procedure 
executes the PRINT command following the line labeled OKAY. 


5.3.3 GOSUB Command 

The GOSUB command transfers control to a labeled subroutine in a command 
procedure. If the label does not exist in the command procedure, the 
procedure cannot continue executing and is forced to exit. You can nest 
the GOSUB command up to 16 times per procedure level. 

The GOSUB command is a local subroutine call; it does not create a new 
procedure level. Because the GOSUB command does not create a new 
procedure level, all labels and local symbols defined in the current command 
procedure level are available to a subroutine invoked with GOSUB. 

The rules for entering subroutine labels are as follows: 

• A label must appear as the first item on a line after the dollar sign. 

• A label can have up to 255 characters. 

• A label can contain no embedded space characters. 
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• A label must be terminated with a colon. 

As the command interpreter encounters labels, it enters them in a special 
section of the local symbol table. The amount of space available for labels 
is limited. If a command procedure uses many symbols and contains many 
labels, the command interpreter may run out of table space and issue an error 
message. If this occurs, include the DELETE/SYMBOL command in your 
procedure to delete symbols as they are no longer needed. 

If a command procedure uses the same label more than once, the new 
definition replaces the existing one in the local symbol table. When duplicate 
labels exist, the GOSUB command transfers control to the label that DCL 
has processed most recently. The GOSUB command uses the following rules 
when processing duplicate labels: 

• If duplicate labels all precede the GOSUB command, control transfers to 
the label nearest the GOSUB command. 

• If duplicate labels precede and follow the GOSUB command, control 
transfers to the preceding label nearest the GOSUB command. 

• If duplicate labels all follow the GOSUB command, control transfers to 
the label nearest the GOSUB command. 

The RETURN command terminates a subroutine and returns control to the 
command following the GOSUB command. You can specify a value for 
$STATUS with the RETURN command that overrides the value that DCL 
assigns to $STATUS at the end of the subroutine. This value must be an 
integer between zero and four or an equivalent expression. If you specify a 
value for $STATUS, DCL interprets this value as a condition code. If you do 
not specify a value for $STATUS, the current value of $STATUS is saved. See 
Chapter 7 for more information about condition codes and $STATUS. 

The following example shows how you can use the GOSUB command to 
transfer control to subroutines. 

$! 

$! GOSUB.COM 
$! 

$ SHOW TIME 
$ GOSUB TEST1 O 

$ WRITE SYS$0UTPUT "GOSUB level 1 has completed successfully." 

$ SHOW TIME 
$ EXIT 
$! 

$! TEST1 GOSUB definition 
$! 

$ TEST1: 

$ WRITE SYS$0UTPUT "This is GOSUB level 1." 

$ GOSUB TEST2 © 

$ RETURN */.Xl © 

$! 

$! TEST2 GOSUB definition 
$! 

$ TEST2: 

$ WRITE SYSSOUTPUT "This is GOSUB level 2." 

$ WAIT 00:00:02 

$ RETURN © 

© The first GOSUB command transfers control to the subroutine labeled 
TEST1. 
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© The procedure executes the commands in subroutine TEST1, branching to 
the subroutine labeled TEST2. 

© The RETURN command in subroutine TEST1 returns control to the main 
command procedure, and passes a value of 1 to $STATUS, indicating 
successful completion. 

© The RETURN command in subroutine TEST2 returns control to 

subroutine TEST1. Note that this command executes before command 3. 


5.3.4 CALL Command 

The CALL command transfers control to a labeled subroutine in a command 
procedure and creates a new procedure level. The CALL command allows 
you to keep more than one related command procedure in a single file, 
making the procedures easier to manage. The subroutine label, which must 
be unique, can precede or follow the CALL command in the command 
procedure. Section 5.3.3 contains rules for entering subroutine labels. 

In addition to the label, you can pass up to eight optional parameters to the 
subroutine. These parameters assign character string values to the symbols 
PI through P8. Separate each parameter with one or more spaces. Use 
quotation marks ("") to specify a null parameter. Use alphanumeric and 
special characters to specify parameters, with the following restrictions. 

• The command interpreter converts alphabetic characters to uppercase 
and uses spaces to delimit each parameter. To pass a parameter that 
contains embedded spaces or literal lowercase letters, place the parameter 
in quotation marks. 

• If the first parameter begins with a slash character (/), enclose the 
parameter in quotation marks. 

• If the parameter contains literal quotation marks and spaces, enclose the 
entire string in quotation marks and use a double set of quotation marks 
within the string. The following example equates the string Never say 
"quit" to PI. 

$ CALL SUB1 "Never say ""quit""" 

• To use a symbol as a parameter, enclose the symbol with apostrophes. 

$ CALL SUB2 ’WHOLE* 

By default, the CALL command sends output to SYS$OUTPUT. The CALL 
command has an optional /OUTPUT qualifier that allows you to direct output 
from the subroutine to a file. The default file type for the output file is LIS. 
Do not use wildcard characters in the output file specification. 

You can nest subroutines called with the CALL command and procedures 
called with the @ (execute procedure) command to a maximum of 32 
command levels. Unless they are masked using the SET SYMBOL command, 
local symbols defined in an outer level are available to any inner procedure 
or subroutine levels and global symbols are available at any command level. 
Labels are valid only for the level in which they are defined. 

The SUBROUTINE and ENDSUBROUTINE commands define the beginning 
and the end of a CALL subroutine. The label defining the entry point to 
the subroutine immediately precedes the SUBROUTINE command. The 
EXIT command may be placed immediately before the ENDSUBROUTINE 
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command, but it is not required to terminate the subroutine. The 
ENDSUBROUTINE command terminates the subroutine and transfers control 
to the command line immediately following the CALL command. 

Command lines in a subroutine execute only when the subroutine is called 
with the CALL command. During the line-by-line execution of the command 
procedure, the command language interpreter skips all commands between 
the SUBROUTINE and the ENDSUBROUTINE commands. 

The following example includes two subroutines called SUB1 and SUB2. The 
subroutines do not execute until they are called with the CALL command. 

$ 

$! CALL.COM 
$ 

$! Define subroutine SUB1 
$! 

$ SUB1: SUBROUTINE 


$ CALL SUB2 !Invoke SUB2 from within SUB1 


$ 0FILE (Invoke another procedure command file 


$ EXIT 

$ ENDSUBROUTINE (End of SUB1 definition 
$! 

$! Define subroutine SUB2 
$! 

$ SUB2: SUBROUTINE 
$ EXIT 

$ ENDSUBROUTINE (End of SUB2 definition 
$! 

$! Start of main routine. At this point, both SUB1 and SUB2 
$! have been defined but none of the previous commands have 
$! been executed. 

$! 

$ START: 

$ CALL/OUTPUT=NAMES.LOG SUB1 "THIS IS PI" 


$ CALL SUB2 "THIS IS PI" "THIS IS P2" 


$ EXIT (Exit this command procedure file 

In this example, the CALL command invokes the subroutine SUB1 and directs 
output to the file NAMES.LOG. Subroutine SUB1 calls subroutine SUB2. The 
procedure executes SUB2, invoking the command procedure FILE.COM with 
the @ (execute procedure) command. When all the commands in SUB1 have 
executed, the CALL command in the main procedure calls SUB2 a second 
time. The procedure exits when SUB2 finishes executing. 
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5.3.5 Loops 

A loop is a group of statements that execute until a condition is met. When 
you write loops, do the following: 

1 Begin the loop with a label. 

2 Test a variable to determine whether you need to execute the commands 
in the loop. (This is the termination variable.) 

3 If you do not need to execute the loop, go to the end of the loop. 

4 If you need to execute the loop, perform the commands in the loop and 
then return to the beginning of the loop. 

You can also write loops that test the termination variable at the end of the 
loop. Note that when you test the termination variable at the end of the loop, 
the commands in the body of the loop are executed at least once. 

The following examples show different ways you can write loops. The first 
example tests the termination variable at the beginning of the loop; the loop 
terminates when the value of the symbol FILE is the null string. 

$ LOOP: 

$ INQUIRE FILE "File (press RET to quit)" 

$ IF FILE .EQS. "" THEN GOTO DONE 
$ ! Process file 


$ GOTO LOOP 
$! 

$ DONE: 


In this example, the INQUIRE command requests a file name. If the response 
is a null value (you pressed CTRL/Z or the RETURN key) the loop does not 
execute. Otherwise, the loop executes repeatedly until you enter a null value. 

The next example uses a counter to control the number of times a loop 
executes. In this example, the loop executes 10 times; the termination variable 
is tested at the end of the loop. 

$! Obtain 10 file names and store them in the 
$! symbols FILE.l through FILE_10 
$! 

$ COUNT = 0 
$ LOOP: 

$ COUNT = COUNT + 1 

$ INQUIRE FILE.’COUNT’ "File" 

$ IF COUNT .LT. 10 THEN GOTO LOOP 
$! 

$ PROCESS.FILES: 
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This example uses the symbol COUNT to keep track of how many times the 
commands in the loop are executed. The example also uses COUNT to create 
the symbol names FILE—1, FILE—2 and so on through FILE—10. Note that 
the value of COUNT is incremented at the beginning of the loop but is tested 
at the end of the loop. Therefore, when COUNT is incremented from 9 to 
10, the loop executes a last time (obtaining a value for FILE_10) before the IF 
statement finds a false result. 

To perform a loop for a known sequence of values, use the F$ELEMENT 
lexical function. The F$ELEMENT function obtains items from a list of 
items separated by delimiters. You must supply the item number, the item 
delimiter, and the list as arguments for F$ELEMENT. See the VMS DCL 
Dictionary for more information. For example: 

$ FILE.LIST = "CHAP1/CHAP2/CHAP3/CHAP4/CHAP5" 

$ NUM = 0 
$! 

$! Process each file listed in FILE.LIST 
$ PR0CESS.L00P: 

$ FILE = F$ELEMENT(NUM,"/",FILE.LIST) 

$ IF FILE .EQS. "/" THEN GOTO DONE 
$ COPY ’FILEMEM MORRIS::DISK3:[DOCSET]*.* 

$ NUM = NUM + 1 

$ GOTO PR0CESS.L00P 

$! 

$ DONE: 

$ WRITE SYSSOUTPUT "Finished copying files." 

$ EXIT 

This command procedure uses a loop to copy the files listed in the symbol 
FILE—LIST to a directory on another node. The first file returned by the 
F$ELEMENT function is CHAP1, the next file is CHAP2, and so on. Each 
time through the loop, the value of NUM is increased so that the next file 
name is obtained. When the F$ELEMENT returns a slash, all the items from 
FILE—LIST have been processed and the loop is terminated. 


5.3.6 Case Statements 


A case statement is a special form of conditional code that executes one out of 
a set of command blocks depending on the value of a variable or expression. 
Although DCL does not provide a case statement, you can perform the 
function of a case statement in the following way: 

1 Equate a symbol to a string that contains a list of options. 

2 Obtain the desired option from the user. 

3 Use the F$LOCATE and F$LENGTH lexical functions to verify that the 
user's option is valid; that is, the option is one of the choices listed. 

4 Use the GOTO command to direct the flow of execution to the 
appropriate block of commands. The labels that identify each block 
of commands should be the same as the options you specify in your 
option list. 

For example, you can rewrite CLEAN.COM (shown in Section 5.2.2) so that 
it verifies that a command is valid at the beginning of the procedure. If the 
command is valid, then the procedure executes the command. Note that the 
labels that identify each command block are the same as the commands in 
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the option list. This allows you to use the symbol COMMAND (which is 
equated to user's request) in the GOTO statement. 

$ COMMAND.LIST = "DELETE/DIRECTORY/EXIT/" + - 
"PRINT/PURGE/TYPE/" 

$! 

$ GET_C0MMAND_L00P: 

$ INQUIRE COMMAND - 

"Enter command (DELETE, DIRECTORY, EXIT, PRINT, PURGE, TYPE)" 

$ IF F$L0CATE(C0MMAND+"/",COMMAND.LIST) .EQ. - 

F$LENGTH(COMMAND.LIST) THEN GOTO ERROR 
$ GOTO ’COMMAND’ 

$! 

$!Execute if user entered DELETE 
$ DELETE: 

$ WRITE SYS$OUTPUT "This is the DELETE section." 


$ GOTO GET_C0MMAND_L00P 

$! 

$!Execute if user entered DIRECTORY 
$ DIRECTORY: 

$ WRITE SYS$OUTPUT "This is the DIRECTORY section." 


$ GOTO GET_C0MMAND_L00P 


$! 

$ EXIT: 

$ WRITE SYS$OUTPUT "Directory ”F$DIRECTORY()’ has been cleaned." 
$ EXIT 
$! 

$! Error section 
$ ERROR: 

$ WRITE SYSSOUTPUT "You entered an invalid command." 

$ GOTO GET.COMMAND.LOOP 


5.4 Terminating Command Procedures 

You can use either the EXIT or STOP command to terminate the execution 
of a command procedure. When included in a command procedure, the 
EXIT command terminates execution of the current command procedure 
and returns control to the previous command level. The STOP command, 
however, returns control to command level 0, regardless of the current 
command level. If you execute the STOP command in a batch job, the batch 
job terminates. 

You can interrupt a command procedure by pressing CTRL/Y and then using 
the EXIT command or STOP command to terminate the procedure. In this 
case, both commands return you to command level 0. For example: 

$ OTESTALL [ret! 

|ctrl/y| 

$ EXITIretI 

$ 
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In the preceding example, you interrupt the procedure TESTALL by pressing 
CTRL/Y. The EXIT command terminates processing of the procedure and 
restores command level 0. Note that you could have also entered the STOP 
command after you interrupted the procedure. 

Note: When you interrupt a command procedure, if the command (or image) 

that you interrupt declares any exit-handling routines, the EXIT command 
gives these routines control. However, the STOP command does not 
execute these routines. 


5.4.1 Using the EXIT Command 

You can use the EXIT command to ensure that a procedure does not execute 
certain lines. For example, if you write an error-handling routine at the end 
of a procedure, you would place an EXIT command before the routine, as 
follows: 


$ EXIT ! End of normal execution path 

$ ERR0R_R0UTINE: 


The EXIT command is also useful for writing procedures that have more than 
one execution path. For example: 

$ START: 

$ IF Pl.EQS. "TAPE" .OR. PI .EQS. "DISK" THEN GOTO ’PI’ 

$ INQUIRE Pi "Enter device (TAPE or DISK)" 

$ GOTO START 

$ TAPE: ! Process tape files 


$ EXIT 

$ DISK: ! Process disk files 


$ EXIT 

To execute this command procedure, you must enter either TAPE or DISK 
as a parameter. The IF command uses a logical OR to test whether either of 
these strings was entered. If so, the GOTO command branches appropriately, 
using the parameter as the branch label. If PI was neither TAPE nor DISK, 
the INQUIRE command prompts for a correct parameter; the GOTO START 
command establishes a loop. 

The commands following each of the labels TAPE and DISK provide different 
paths through the procedure. The EXIT command before the label DISK 
ensures that the commands after the label DISK do not execute unless the 
procedure branches explicitly to the label DISK. 

Note that the EXIT command at the end of the procedure is not required 
because the end-of-file of the procedure causes an implicit EXIT command. 
Use of the EXIT command, however, is recommended. 
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5.4 Terminating Command Procedures 


5.4.2 Passing Status Values with the EXIT Command 

When a command procedure exits, the command interpreter returns the 
condition code for the previous command in a special symbol called 
$STATUS. (The condition code provides information about whether the most 
recent command executed successfully. See Chapter 7 for more information 
on condition codes.) 

When you use the EXIT command in a command procedure, you can specify 
a value that overrides the value that DCL would have assigned to $STATUS. 
This value, called a status code, must be specified as an integer expression. 

When a command procedure contains nested procedures to create multiple 
command levels, you can use the EXIT command to return a value that 
explicitly overrides the default condition codes. 

For example, suppose the procedure A.COM contains the following lines: 

$! This is file A.COM 
$! 

$ OB 


The procedure B.COM contains the following lines: 

$! This is file B.COM 
$! 

$ ON WARNING THEN GOTO ERROR 


$ ERROR: 

$ EXIT 1 

The ON command means that if any warnings, errors, or severe errors occur 
when B.COM is executing, the procedure is directed to the label ERROR. 
Here, the condition code is explicitly set to 1, indicating success. Therefore, 
when B.COM terminates it passes a success code back to A.COM regardless 
of whether an error occurred. 


5.4.3 Using the STOP Command 

You can use the STOP command in a command procedure or batch job to 
ensure that all procedure levels are terminated if a severe error occurs. For 
example: 

$ ON SEVERE.ERROR THEN STOP 


If you include this line in a command procedure and a severe error occurs, the 
command procedure terminates. In a command procedure that is executed 
interactively, control is returned to command level 0. In a batch job, the job 
terminates. 
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File Input/Output 




6.1 


The basic steps in reading and writing files from a command procedure are as 
follows: 

• Use the OPEN command to open a file. The OPEN command assigns 
a logical name to the file and specifies whether the file is to be read, 
written, or both read and written. 

• Use the READ or WRITE commands to read or write records to the file. 
When you perform input and output to files, you usually design a loop 
to read a record, process the record, and write the modified record to 
either the same or to another file. You execute the commands in this loop 
(reading, processing, and writing records) until you are through. 

• Use the CLOSE command to close the file. Unless you explicitly close it, 
a file remains open until you log out. 

This chapter describes how to use the OPEN, READ, WRITE, and CLOSE 
commands. In addition, it shows how to modify files and how to handle 
errors when you perform file operations. 


Commands for File I/O 

The following sections describe the DCL commands for performing input and 
output to files. 



6.1.1 



OPEN Command 

The OPEN command can open sequential, relative, or indexed sequential 
access method files. When opening a file, the OPEN command assigns a 
logical name to the file and places the name in the process logical name table. 
Subsequent READ, WRITE, and CLOSE commands use this logical name to 
refer to the file. 

When you open a file from a command procedure, be sure to include the 
file's device and directory names. This ensures that your command procedure 
opens the correct file regardless of the directory from which you execute the 
command procedure. 

The OPEN command opens files as process-permanent. Therefore, these files 
remain open for the duration of your process unless you explicitly close them 
(with the CLOSE command). These files are subject to RMS restrictions on 
using process-permanent files. 

You do not have to explicitly open SYS$INPUT, SYS$OUTPUT, 
SYS$COMMAND, and SYS$ERROR in order to read or write to them because 
the system opens these files for you when you log in. For more information 
on reading or writing to process-permanent files, see Chapter 3. 

The following sections describe how to open a file for reading, writing, and 
both reading and writing, and how to open a shareable file. 


6-1 









File Input/Output 

6.1 Commands for File I/O 


6.1.1.1 Opening a File for Reading 

To open a file for reading, use the /READ qualifier; this is the default when 
you use the OPEN command. The following example opens a file for reading: 

$ OPEN/READ INFILE DISK4:[MURPHY]STATS.DAT 

When you open a file for reading, you can read, but not write records. The 
OPEN/READ command places the record pointer at the beginning of the file. 
Each time you read a record, the pointer moves to the next record. 


6.1.1.2 Opening a File for Writing 

To open a file for writing, use either the /WRITE qualifier or the /APPEND 
qualifier. These qualifiers are mutually exclusive, so you can use only one of 
them on a command line. 

The /WRITE qualifier (used without the /READ qualifier) creates a new file 
and places the record pointer at the beginning of the file. The OPEN/WRITE 
command always creates a sequential file in print file format. The record 
format for the file is variable with fixed control (VFC), with a two-byte record 
header. Note that if you specify a file that already exists, the OPEN/WRITE 
command opens a new file with a version number one greater than the 
existing file. 

The following example opens a file for writing and writes records to the file: 

$ OPEN/WRITE OUTFILE DISK4:[MURPHY]NAMES.DAT 
$ UPDATE: 

$ INQUIRE NEW.RECORD "Enter name" 

$ WRITE OUTFILE NEW.RECORD 
$ IF OUTFILE .EQS. "" THEN GOTO EXIT.CODE 
$ GOTO UPDATE 
$ EXIT.CODE: 

$ CLOSE OUTFILE 
$ EXIT 

The /APPEND qualifier, unlike the /WRITE qualifier, does not open a new 
version of a file. The /APPEND qualifier opens an existing file and positions 
the record pointer at the end of the file. This allows you to add records to the 
end of a file. 

The following command procedure appends records to the end of the file 
NAMES.DAT: 

$ OPEN/APPEND OUTFILE DISK4:[MURPHY]NAMES.DAT 
$ INQUIRE NEW.RECORD "Enter name" 

$ WRITE OUTFILE NEW.RECORD 


$ CLOSE OUTFILE 
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6.1 Commands for File I/O 


6.1.1.3 Opening a File for Reading and Writing 

To open a file for reading and writing, use both the /READ and /WRITE 
qualifiers. For example: 

$ OPEN/READ/WRITE FILE DISK4:[MURPHY]STATS.DAT 

This OPEN command places the record pointer at the beginning of the file 
STATS.DAT so you can read the first record. When you use this method of 
opening a file, you can only replace the record you have most recently read; 
you cannot write new records to the end of the file. Also, a revised record 
must be exactly the same size as the record being replaced. 


6.1.1.4 Opening Shareable Files 

To open a shareable file, use the /SHARE qualifier when you open the 
file. When you use the /SHARE qualifier, other users may read or write 
to the file. Use /SHARE=READ to allow other users to read the file; use 
/SHARE=WRITE to allow other users to write to the file. In addition, other 
users may access the file with the TYPE or SEARCH command. 


6.1.2 READ Command 

Use the READ command to read a record and assign its contents to a symbol. 
For example: 

$ OPEN/READ INFILE DISK4:[MURPHY]STATS.DAT 
$ READ/END_OF_FILE=END_LOOP INFILE RECORD 


$END_L00P: 

$ CLOSE INFILE 
$ EXIT 

In this example, the READ command reads a record from the file INFILE and 
assigns the record's contents to the symbol RECORD. 

When you specify a symbol name for the READ command, the command 
interpreter places the symbol name in the local symbol table for the current 
command level. If you use the same symbol name for more than one READ 
command, each READ command redefines the value of the symbol name. 
For example: 

$ BEGIN: 

$ READ/END_OF_FILE=END_LOOP INFILE RECORD 


$ GOTO BEGIN 


$ END.LOOP: 

$ CLOSE INFILE 
$ EXIT 

Each time through this loop, the READ command reads a new record from 
the input file and uses this record to redefine the value of the symbol 
RECORD. 
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6.1 Commands for File I/O 


In order to read from a file, the file must be opened with read access. You 
can read records that are less than or equal to 1024 characters in length. 


6.1.2.1 Designing Read Loops 

When you read from files, you generally read and process each record until 
you reach the end of the file. To determine when you reach the end of a 
file, use the /END—OF—FILE qualifier with the READ command. By using 
this qualifier, you can construct a loop to read records from a file, process 
the records, and exit from the loop when you have finished reading all the 
records. For example: 

$ OPEN/READ INFILE DISK4:[MURPHYjSTATS.DAT 
$ READ.L00P: 

$ READ/END_0F_FILE=END_L00P INFILE RECORD 


$ GOTO READ_L00P 
$! 

$ END.L00P: 

$ CLOSE INFILE 
$ EXIT 

In this example, the procedure executes the READ command repeatedly 
until the end-of-file status is returned. Then, the procedure branches to the 
line labeled END__LOOP. Note that the labels you specify for /END-OF- 
FILE qualifiers are subject to the same rules as labels specified for a GOTO 
command. 

You should always use the /END—OF_FILE qualifier when you use the 
READ command in a loop. Otherwise, when the error condition indicating 
the end-of-file is returned by the VMS Record Management Services (VMS 
RMS), the command interpreter performs the error action specified by the 
current ON command. For example, VMS RMS returns the error status 
%RMS-E-EOF. This causes a command procedure to exit unless the procedure 
has established its own error handling. 


6.1.2.2 Reading Records Randomly from Indexed Sequential Files 

You can use the READ command with the /INDEX and /KEY qualifiers 
to read records randomly from indexed sequential access method files. The 
/KEY and /INDEX qualifiers specify that a record should be read from the file 
by finding the specified key in the index, and returning the record associated 
with that key. If you do not specify an index, the primary index, 0, is used. 

After you read a record randomly, you can read the remainder of the file 
sequentially from that point using READ commands without the /KEY or 
/INDEX qualifiers. 

You can use the READ command with the /DELETE qualifier to delete 
records from indexed sequential access method files. The /DELETE qualifier 
causes a record to be deleted from a file after it has been read. Use the 
/DELETE qualifier with the /INDEX and /KEY qualifiers to delete a record 
specified by a given key. 

For more information on the /DELETE, /INDEX, and /KEY qualifiers, see the 
description of the READ command in the VMS DCL Dictionary . 
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6.1 Commands for File I/O 


6.1.3 WRITE Command 

Use the WRITE command to write a record to a file. Specify the data to 
be written as a character string expression, or as a list of expressions. For 
example: 

$ OPEN/WRITE OUTFILE DISK4:[MURPHY]NEW_STATS.DAT 
$ WRITE OUTFILE "File created April 15, 1984" 


$ CLOSE OUTFILE 

When you specify data for the WRITE command, follow the rules for 
character string expressions described in Chapter 2. Note that the WRITE 
command automatically substitutes symbols and lexical functions, as follows: 

$ OPEN/WRITE OUTFILE DISK4:[MURPHY]NEW.STATS.DAT 
$ INQUIRE NAME "Enter name" 

$ WRITE OUTFILE NAME 


In this example, the WRITE command writes the value of the symbol NAME 
to NEW_STATS.DAT. 

You can intersperse symbol names and literal character strings within a 
WRITE command, as follows: 

$ WRITE OUTFILE "Count is ".COUNT,"." 

If the value of COUNT is 4, this WRITE command writes the following string 
to the file OUTFILE: 

Count is 4. 

Another way to mix literal strings with symbol names is to place the entire 
string within quotation marks and use double apostrophes to request symbol 
substitution. For example: 

$ WRITE OUTFILE "Count is ’’COUNT’." 

Figure 6-1 shows different ways of specifying data for the WRITE command. 

The WRITE command can write records only to files that have been opened 
for writing. (You can use either the /WRITE or the /APPEND qualifiers 
to open files for writing.) When the WRITE command writes a record, 
it positions the record pointer after the record just written. The WRITE 
command can write a record that is up to 2048 bytes long. 

If you want to write a record that is longer than 1024 bytes, or if any 
expression in the WRITE command is longer than 255 bytes, you must 
use the /SYMBOL qualifier when you write the record. See the description 
of the WRITE command in the VMS DCL Dictionary for more information on 
writing long records. 

You can use the WRITE command with the /UPDATE qualifier to change a 
record rather than insert a new one. To use the /UPDATE qualifier, you must 
have opened a file for both reading and writing. (See Section 6.2.1.) 
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Figure 6-1 Symbol Substitution with the WRITE Command 


$ 0FIGURE 

TYPE DATA.OUT 
the character string 
ABC 

COUNT IS a 
MODE IS INTERACTIVE 
FOURTH PARAMETER 
$ 


o 

o 

© 

o 

0 


DBA1:[HIGGINS]FIGURE.COM 


$ 

ABC = 

"the character string" 

$ 

COUNT 

= a 


$ 

pa = 

"fourth parameter" 


$ 

OPEN 

WRITE OUTFILE DATA.OUT 

$ 

WRITE 

OUTFILE ABC 


$ 

WRITE 

OUTFILE "ABC" 


$ 

WRITE 

OUTFILE "COUNT IS 

"»COUNT 

$ 

WRITE 

OUTFILE "MODE IS ' 

' F$MODE( ) ' " 

$ 

WRITE 

OUTFILE P ' COUNT ' 


$ 

CLOSE 

OUTFILE 



O The WRITE command automatically performs symbol substitution on character strings that are not enclosed in 
quotation marks; substitution is not recursive. 

© If a character string is enclosed in quotation marks, the WRITE command does not perform symbol substitution. 

© When two or more symbol names or character strings are specified, the WRITE command concatenates the strings 
before it writes the record to the output file. 

© Within character strings, the command interpreter performs substitution requested by apostrophes during command 
input; the WRITE command executes the results. 

© If the data specified for a WRITE command contains an apostrophe, the command interpreter performs symbol 
substitution during command input (as in ©); the WRITE command performs substitution on the resulting command 
string. 

ZK-830-82 


6.1.4 CLOSE Command 

The CLOSE command closes a file and deassigns the logical name created by 
the OPEN command. For example: 

$ OPEN INFILE DISK4:[MURPHY]STATS.DAT 


$ CLOSE INFILE 

Be sure to close all files you open in a command procedure before the 
command procedure terminates. If you fail to close an open file, the file 
remains open when the command procedure terminates and the logical name 
assigned to the open file is not deleted from the process logical name table. 


6.2 Modifying a File 

You can modify files in the following three ways: 

• Update records in the current version of the file. 

• Read records from an input file and create a new version of the file that 
incorporates your changes. 

• Append records to the current version of the file. 

The following sections describe these methods. 
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6.2 Modifying a File 


6.2.1 Updating Records in a File 

When you update a file, you can replace existing records although you cannot 
add new records. When you update a file, you do not create a new version of 
the input file. 

In a sequential file, you can update individual records only if the revised 
records are exactly the same size as the existing records. In an indexed 
sequential file, you can update individual records regardless of the record 
sizes. 

To update records in a file, do the following: 

1 Open the file for both read and write access. 

2 Use the READ command to obtain the records that you want to modify. 

3 Modify the record. In a sequential file, the text of this record must be 
exactly the same size as the original record. If the text of the modified 
record is shorter, pad the record with spaces, adding spaces to the end of 
the modified record until it is the same length as the original record. If 
the text of the modified record is longer, you cannot use this method to 
modify the file. 

4 Use the WRITE command with the /UPDATE qualifier to write the 
modified record back to the file. 

5 Continue using the READ and WRITE commands to read and update the 
records in the file until you have finished updating the file. 

6 Use the CLOSE command to close the file. 

After you close the file, it contains the same version number as when you 
started even though individual records have been changed. 

The following command procedure shows how to make changes to a 
sequential file by reading and updating individual records. 

$! Open STATS.DAT and assign it the logical name FILE 
$! 

$ OPEN/READ/WRITE FILE DISK4:[MURPHY]STATS.DAT 
$ BEGIN_L00P: 

$! Read the next record from FILE into the symbol RECORD 

$ READ/END_OF_FILE=END_LOOP FILE RECORD 

$! Display the record and see if the user wants to change it 

$! If yes, get the new record. If no, repeat loop 

$! 

$ PROMPT: 

$ WRITE SYSSOUTPUT RECORD 

$ INQUIRE/NOPUNCTUATION OK "Change? Y or N [Y] " 

$ IF OK .EQS. "N" THEN GOTO BEGIN_L00P 

$ INQUIRE NEW.RECORD "New record" 

$! Compare the old and new records 

$! If old record is shorter than new record, issue an error message 
$! If old record and new record are the same length, write the record 
$! Otherwise pad new record with spaces so it is correct length 
$! 

$ 0LD_LEN = FSLENGTH(RECORD) 

$ NEW.LEN = F$LENGTH(NEW_RECORD) 

$ IF 0LD_LEN .LT. NEW_LEN THEN GOTO ERROR 

$ IF 0LD_LEN .EQ. NEW.LEN THEN GOTO WRITE.RECORD 

$ SPACES = " " 

$ PAD = F$EXTRACT(0,0LD_LEN-NEW_LEN,SPACES) 
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$ 

$! 
$ 
$ 
$ 
$• 
$ 
$ 
$ 
$! 
$ 
$ 
$ 


NEW.RECORD = NEW.RECORD + PAD 


WRITE.RECORD: 

WRITE/UPDATE FILE NEW.RECORD 
GOTO BEGIN.LOOP 


ERROR: 


WRITE SYS$OUTPUT "Error — New record is too long" 
GOTO PROMPT 


END.LOOP: 


CLOSE FILE 
EXIT 


6.2.2 Creating a New Output File 


To make extensive changes to a file, you may need to rewrite the entire 

file. Because you are creating a new output file, you can modify the size of 

records, add records, or delete records. 

To create a new output file, follow these steps: 

1 Use the OPEN command to open a file for read access. This is the input 
file, the file you are modifying. 

2 Use the OPEN command to open a new file for write access. This is the 
output file, the file that you are creating. If you give the output file the 
same name as the input file, the output file will have a version number 
one greater than the input file. 

3 Use the READ command to read a record from the file you are modifying. 

4 If the record needs to be changed, modify the record and then use the 
WRITE command to write the record to the new file. If the record is 
correct, then write it directly to the new file. If the record is to be deleted, 
do not write it to the new file. 

5 Continue reading and processing records until you have finished. 

6 Use the CLOSE command to close both the input and the output files. 

The following example shows a command procedure that reads a record from 

an input file, processes the record, and copies the record into an output file. 
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$! Open STATS.DAT for reading and assign it 
$! the logical name INFILE 

$! Open a new version of STATS.DAT for writing 
$! and assign it the logical name OUTFILE 
$! 

$ OPEN/READ INFILE DISK4:[MURPHY]STATS.DAT 
$ OPEN/WRITE OUTFILE DISK4:[MURPHY]STATS.DAT 
$! 

$ BEGIN.LOOP: 

$! Read the next record from INFILE into the symbol RECORD 
$! 

$ READ/END_OF_FILE=END_LOOP INFILE RECORD 

$! Display the record and see if the user wants to change it 

$! If yes, get the new record. If no, write record directly 

$! to OUTFILE 

$! 

$ PROMPT: 

$ WRITE SYS$OUTPUT RECORD 

$ INQUIRE/NOPUNCTUATION OK "Change? Y or N [Y] " 

$ IF OK .EQS. "N" THEN GOTO WRITE.RECORD 

$ INQUIRE RECORD "New record" 

$! 

$ WRITE.RECORD: 

$ WRITE OUTFILE RECORD 

$ GOTO BEGIN.LOOP 

$! 

$! Close input and output files 
$! 

$ END.LOOP: 

$ CLOSE INFILE 

$ CLOSE OUTFILE 

$ EXIT 


6.2.3 Appending Records to a File 

The OPEN/APPEND command allows you to append records to the end of 

an existing file. To append records, follow these steps: 

1 Use the OPEN command with the /APPEND qualifier to position the 
record pointer at the end of the file. The /APPEND qualifier does not 
create a new version of the file. 

2 Use the WRITE command to write new data records. Continue adding 
records until you are through. 

3 Use the CLOSE command to close the file. 

The following example appends new records to a file. 
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$! Open STATS.DAT to append files and assign 
$! it the logical name FILE 
$! 

$ OPEN/APPEND FILE DISK4:[MURPHY]STATS.DAT 
$! 

$ BEGIN.LOOP: 

$! Obtain record to be appended and place this 
$! record in the symbol RECORD 
$! 

$ PROMPT: 

$ INQUIRE RECORD - 

"Enter new record (press RET to quit) " 

$ IF RECORD .EQS. "" THEN GOTO END_L00P 

$! Write record to FILE 
$! 

$ WRITE FILE RECORD 

$ GOTO BEGIN.LOOP 

$! 

$! Close FILE and exit 
$! 

$ END.LOOP: 

$ CLOSE FILE 

$ EXIT 


6.3 Handling I/O Errors 

Use the /ERROR qualifier with the OPEN, READ, WRITE, and CLOSE 
commands to handle errors. The /ERROR qualifier directs control to a label 
in your command procedure if an I/O error occurs. Also, the /ERROR 
qualifier suppresses error messages that would normally be displayed on the 
terminal. The following example uses the /ERROR qualifier with the OPEN 
command: 

$ OPEN/READ/ERROR=CHECK FILE CONTINGEN.DOC 


$ CHECK: 

$ WRITE SYSSOUTPUT "Error opening file" 

The OPEN command requests that the file CONTINGEN.DOC be opened for 
reading. If the file cannot be opened (for example, if the file does not exist), 
the OPEN command returns an error condition. Control is then transferred to 
the label CHECK. 

The error path specified by the /ERROR qualifier overrides the current ON 
condition established for the command level. If an error occurs and the target 
label is successfully given control, the reserved global symbol $STATUS 
retains the code for the error. You can use the F$MESSAGE lexical function 
in your error-handling routine to display the message in $STATUS: 

$ OPEN/READ/ERROR=CHECK FILE ’PI * 
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$ CHECK: 

$ ERR.MESSAGE = F$MESSAGE($STATUS) 

$ WRITE SYS$OUTPUT "Error opening file: ",P1 
$ WRITE SYSSOUTPUT ERR.MESSAGE 


If an error occurs while you are using the OPEN, READ, WRITE, or CLOSE 
commands and you did not specify an error action, the current ON command 
action is taken. (See Chapter 7.) 

When a READ command receives an end of file message, the error action is 
determined in the following way. If you used the /END_OF_FILE qualifier, 
control is passed to the specified label. If /END_OF_FILE is not specified, 
control is given to the label specified with the /ERROR qualifier. If neither 
qualifier is specified, the current ON action is taken. 


6-11 















7 


Controlling Error Conditions and CTRL/Y Interrupts 


This chapter describes what happens when an error condition or a CTRL/Y 
interrupt occurs while a command procedure is executing. It also describes 
how you can use the ON, SET [NO]ON, and SET [NO]CONTROL commands 
to change the defaults for handling error conditions and CTRL/Y interrupts. 


7.1 Detecting Errors in Command Procedures 

When each DCL command in a command procedure completes execution, the 
command interpreter saves a condition code that describes the reason why 
the command terminated. This code can indicate successful completion or it 
can identify an informational or error message. 

The command interpreter examines the condition code after it performs each 
command in a command procedure. If an error that requires special action 
has occurred, the system performs the action. Otherwise, the next command 
in the procedure executes. 


7.1.1 Condition Codes and $STATUS 

The command interpreter saves the condition code as a 32 bit longword in 
the reserved global symbol $STATUS. $STATUS conforms to the format of a 
VMS message code as follows: 

• Bits 0-2 contain the severity level of the message. 

• Bits 3-15 contain the message number. 

• Bits 16-27 contain the number associated with the facility that generated 
the message. 

• Bits 28-31 contain internal control flags. 

When a command completes successfully, $STATUS has an odd value. (Bits 
0-2 contain a 1 or a 3.) When any type of warning or error occurs, $STATUS 
has an even value. (Bits 0-2 contain a 0, 2, or 4.) The command interpreter 
maintains and displays the current hexadecimal value of $STATUS. Display 
the ASCII translation of $STATUS by entering the following commands: 

$ SHOW SYMBOL $STATUS 
$STATUS = " */,X109110A2" 

$ WRITE SYSSOUTPUT F$MESSAGE( # /.X109110A2) 

•/.CREATE-E-OPENOUT, error opening !AS as output 
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7.1.2 Severity Levels and $SEVERITY 

The low-order three bits of $STATUS represent the severity of the condition 
that caused the command to terminate. This portion of the condition code is 
contained in the reserved global symbol $SEVERITY. $SEVERITY can have 
the values 0 through 4, with each value representing one of the following 
severity levels: 

Value Severity 

0 Warning 

1 Success 

2 Error 

3 Information 

4 Fatal error 


Note that the success and information codes have odd numeric values and 
warning and error codes have even numeric values. You can test for the 
successful completion of a command with IF commands that perform logical 
tests on $SEVERITY or $STATUS as follows: 

$ IF $SEVERITY THEN GOTO OKAY 
$ IF $STATUS THEN GOTO OKAY 

These IF commands branch to the label OKAY if $SEVERITY and $STATUS 
have true (odd) values. When the current value in $SEVERITY and $STATUS 
is odd, the command or program completed successfully. If the command or 
program did not complete successfully, then $SEVERITY and $STATUS are 
even; therefore the IF expression is false. 

Instead of testing that a condition is true, you can test whether it is false. For 
example: 

$ IF .NOT. $STATUS THEN ... 

The command interpreter uses the severity level of a condition code to 
determine whether to take the action defined by the ON command as 
described in Section 7.2.1. 


7.1.3 Commands That Do Not Set $STATUS 

Most DCL commands invoke system utilities that generate status values and 
error messages when they complete. However, there are several commands 
that do not change the values of $STATUS and $SEVERITY if they complete 
successfully. These commands are as follows: 

CONTINUE IF 

DECK SET SYMBOL/SCOPE 

DEPOSIT SHOW STATUS 

EOD SHOW SYMBOL 

EXAMINE STOP 

GOTO WAIT 
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7.1 Detecting Errors in Command Procedures 


If any of these commands results in a nonsuccessful status, however, that 
condition code will be placed in $STATUS, and the severity level will be 
placed in $SEVERITY. 


7.2 Error Condition Handling 

By default, the command interpreter executes an EXIT command when a 
command results in an error or severe error. This causes the procedure to exit 
to the previous command level. For other severity levels (success, warning, 
and informational) the command procedure continues. 

There is one exception to the way that the command interpreter handles 
errors. If you reference a label in a command procedure and the label does 
not exist (for example, if you include the command GOTO ERR1 and ERR1 
is not used as a label in the procedure) then the GOTO command issues a 
warning and the command procedure exits. You can, however, override this 
behavior if you use the ON command to specify an action for the command 
procedure to take on warnings. (Section 7.2.1 describes the ON command.) 

When the system issues an EXIT command as part of an error handling 
routine, it passes the value of $STATUS back to the previous command 
level, with one change. The command interpreter sets the high-order digit 
of $STATUS to 1 so that the command interpreter does not redisplay the 
message associated with the status value. 

For example, the following command procedure TEST.COM contains an error 
in the output file specification: 

$ CREATE DUMMY.DAT\ 

THIS IS A TEST FILE 
$ SHOW TIME 

When you execute the procedure, the CREATE command returns an error 
in $STATUS and displays the corresponding message. The command 
interpreter then examines the value of $STATUS, determines that an error 
occurred, issues an EXIT command, and returns the value of $STATUS. When 
the procedure exits, the error message is not redisplayed, as the CREATE 
command already displayed the message once. At DCL command level you 
can see that $STATUS contains the error message, but the high-order digit 
has been set to 1. 

$ @TEST 

'/.CREATE-E-OPENOUT, error opening DUMMY. DAT as output 
-RMS-F-SYN, file specification syntax error 

•/.DCL-W-SKPDAT, image data (records not beginning with "$") ignored 
$ SHOW SYMBOL SSTATUS 
$STATUS = "•/.X109110A2" 

$ WRITE SYS$OUTPUT F$MESSAGE( # /.X109110A2) 

•/.CREATE-E-OPENOUT, error opening !AS as output 

You can use the ON and SET [NO]ON commands to change the way that the 
system responds to errors in command procedures. 
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7.2 Error Condition Handling 


7.2.1 ON Command 

The ON command specifies an action to be performed if an error of a 
particular severity or worse occurs. If such an error occurs, the system 
takes the following actions: 

• The action specified by the ON command is performed. 

• The system sets $STATUS and $SEVERITY to indicate the result of the 
specified ON action. (In general, these are set to success.) 

• The default error action (to exit if an error or severe error occurs) is reset. 

The format of the ON command is as follows: 

ON condition THEN [$] command 

You can specify error conditions with one of the keywords WARNING, 
ERROR, or SEVERE—ERROR. If an ON command action is established for a 
specific severity level, the command interpreter performs the specified action 
when errors of the same or worse severity occur. When less severe errors 
occur, the command interpreter continues processing the file. Table 7-1 
summarizes how the ON command controls error handling. 


Table 7-1 ON Command Keywords and Actions 


ON Keyword 

Action Taken 

WARNING 

Command procedure performs the specified action if a 
warning, error, or severe error occurs. 

ERROR 

Command procedure performs the specified action if an error 
or severe error occurs; the procedure continues if a warning 


occurs. 

SEVERE_ERROR 

Command procedure performs the specified action if a 
severe (fatal) error occurs; the procedure continues if a 
warning or error occurs. 


For example, if you want to override the default error handling so that 
a procedure exits when warnings, errors, or severe errors occur, use the 
following command: 

$ ON WARNING THEN EXIT 

An ON command action is executed only once; thus, after a command 
procedure performs the action specified in an ON command, the default 
error action is reset. For example, suppose that your procedure includes the 
following command: 

$ ON ERROR THEN GOTO ERR1 

In this case, the command procedure executes normally until an error or 
severe error occurs. If such an error occurs, then the procedure resumes 
executing at ERR1, $STATUS and $SEVERITY are set to success, and the 
default error action is reset. If a second error occurs before another ON 
or SET NOON command is executed, the procedure exits to the previous 
command level. 
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7.2 Error Condition Handling 


The action specified by an ON command applies only within the command 
level in which the command is executed. Therefore, if you execute an ON 
command in a procedure that invokes another procedure, the ON command 
action does not apply to the nested procedure. 

Note: Only one ON statement can be in effect at any one time. If more than one 
ON statement has been issued, only the last one is in effect. 

Figure 7-1 illustrates ON command actions. Also, the sample procedures 
FORTUSER.COM and CALC.COM in Appendix A illustrate the use of the 
ON command to establish error handling. 

Figure 7-1 ON Command Actions 


$ 0FORT 



DBA1 :[HIGGINS]FORT.COM 


$ ON ERROR THEN CONTINUE 
$ FORTRAN A 


$ FORTRAN B 


$ ON WARNING THEN EXIT 


$ FORTRAN C 


$ EXIT 


O 

© 

© 

© 


Q This ON command overrides the default command action (on warning, continue; on error or severe error, exit). If an 
error or severe error occurs while A.FOR is being compiled, the command procedure continues with the next 
command. 

0 The default command action is reset if the previous ON command takes effect. Thus, if an error or severe error 
occurs while both A.FOR and B.FOR are being compiled, the command procedure exits. 

Q If the command procedure does not exit before this command is executed, this command action takes effect. 

Q If a warning, error, or severe error occurs while C.FOR is being compiled, the command procedure exits. 
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7.2.2 Disabling Error Checking 

You can prevent the command interpreter from checking the status returned 
from commands by using the SET NOON command in your command 
procedure. When you use the SET NOON command, the command 
interpreter continues to place values in $STATUS and $SEVERITY, but 
does not perform any error checking. You can restore error checking with the 
SET ON command or with an ON command. For example: 

$ SET NOON 
$ RUN TESTA 
$ RUN TESTB 
$ SET ON 
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7.2 Error Condition Handling 


The SET NOON command preceding these RUN commands ensures that the 
command procedure continues if either of the programs TESTA or TESTB 
return an error condition. The SET ON command restores the default error 
checking by the command interpreter. 

When a procedure disables error checking, it can explicitly check the value of 
$STATUS following the execution of a command or program. For example: 

$ SET NOON 
$ FORTRAN MYFILE 
$ IF $STATUS THEN LINK MYFILE 
$ IF SSTATUS THEN RUN MYFILE 
$ SET ON 

In the previous example, the first IF command checks whether $STATUS 
has a true value (that is, if it is an odd numeric value). If so, the FORTRAN 
command was successful and the LINK command executes. After the LINK 
command executes, $STATUS is tested again. If $STATUS is odd, the RUN 
command executes; otherwise, the RUN command does not execute. The 
SET ON command restores the current ON condition action; that is, whatever 
condition was in effect before the SET NOON command was executed. 

The SET ON or SET NOON command applies only at the current command 
level, that is, the command level at which the command is executed. If you 
use the SET NOON command in a command procedure that calls another 
command procedure, the default error checking mechanism will be in effect 
within the nested procedure. Note that SET NOON has no meaning when 
entered interactively at command level 0. 


7.3 Handling CTRL/Y Interrupts 

By default, when you press CTRL/Y while a command procedure is 
executing, the command interpreter prompts for command input at a special 
command level called CTRL/Y command level. From CTRL/Y command 
level, you can enter DCL commands that are executed within the command 
interpreter, and then resume execution of the command procedure with the 
CONTINUE command. In addition, you can stop the procedure by entering a 
DCL command that forces the command procedure to stop executing. 

You can override the way that command procedures process CTRL/Y 
interrupts by using the ON command as described in Section 7.3.2. 


7.3.1 Interrupting a Command Procedure 

You can interrupt a command procedure that is executing interactively 
by pressing CTRL/Y. When you press CTRL/Y, the command interpreter 
establishes a new command level, called the CTRL/Y level, and prompts for 
command input. When the interruption occurs depends on the command or 
program that is executing: 

• If the command is executed by the command interpreter itself (for 
example, IF, GOTO, or an assignment statement), the command 
completes execution before the command interpreter prompts for a 
command at the CTRL/Y level. 
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7.3 Handling CTRL/Y Interrupts 


• If the command or program is a separate image (that is, an image other 
than the command interpreter), the command is interrupted and the 
command interpreter prompts for a command at the CTRL/Y level. 

At the CTRL/Y level, the command interpreter stores the status of all 
previously established command levels, so that it can restore the correct 
status after any CTRL/Y interrupt. 

After you interrupt a procedure, you can do the following: 

• Enter a DCL command that is executed within the command interpreter. 
Among these commands are the SET VERIFY, SHOW TIME, SHOW 
TRANSLATION, ASSIGN, EXAMINE, DEPOSIT, SPAWN and ATTACH 
commands. After you enter one or more of these commands, you can 
resume the execution of the procedure with the CONTINUE command. 
(See Table 3-1 for a complete list of commands that are executed within 
the command interpreter.) 

When you enter the CONTINUE command, the command procedure 
resumes execution with the interrupted command or program, or with the 
line after the most recently completed command. 

• Enter a DCL command that executes another image. When you enter any 
command that invokes a new image, the command interpreter returns 

to command level 0 and executes the command. This terminates the 
command procedure's execution. Any exit handlers declared by the 
interrupted image are allowed to execute before the new image is started. 

• Enter the EXIT or STOP command to terminate the command procedure's 
execution. If you use the EXIT command, exit handlers declared by the 
interrupted image are allowed to execute. However, the STOP command 
does not execute these routines. 

If you interrupt the execution of a privileged image, you can enter only 
the CONTINUE, SPAWN, or ATTACH commands if you want to save the 
context of the image. If you enter any other commands (except from within 
a subprocess that you have spawned or attached to), the privileged image is 
forced to exit. 


7.3.2 Setting a CTRL/Y Action Routine 

The ON command, which defines an action to be taken in case of error 
conditions, also provides a way to define an action routine for a CTRL/Y 
interrupt that occurs during execution of a command procedure. The action 
that you specify overrides the default CTRL/Y action (that is, to prompt for 
command input at the CTRL/Y command level). 

For example: 

$ ON C0NTR0L_Y THEN EXIT 

If a procedure executes this ON command, a subsequent CTRL/Y interrupt 
during the execution of the procedure causes the procedure to exit. Control is 
passed to the previous command level. 
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7.3 Handling CTRL/Y Interrupts 


When you press CTRL/Y to interrupt a procedure that uses ON CONTROL— 
Y, the following actions are taken: 

• If the command currently executing is a command executed within the 
command interpreter, the command completes and the CTRL/Y action is 
taken. 

• If the current command or program is executed by an image other than 
the command interpreter, the image is forced to exit and the CTRL/Y 
action is taken. If the image has declared an exit handler, however, the 
exit handler is executed before the CTRL/Y action is taken. The image 
cannot be continued following the CTRL/Y action. 

The execution of a CTRL/Y action does not automatically reset the default 
CTRL/Y action (that is, to prompt for command input at the CTRL/Y 
command level). A CTRL/Y action remains in effect until one of the 
following conditions occurs: 

• The procedure terminates (as a result of pressing CTRL/Y, executing an 
EXIT or STOP command, or a default error condition handling action) 

• Another ON CONTROL _Y command is executed 

• The procedure executes the SET NOCONTROL=Y command (See 
Section 7.3.3.) 

For example, a procedure can contain the following line: 

$ ON CONTROL.Y THEN SHOW TIME 

When this procedure executes, each CTRL/Y interrupt results in the execution 
of the SHOW TIME command. After each SHOW TIME command executes, 
the procedure resumes execution at the command following the command 
that was interrupted. 

Figure 7-2 illustrates two ON CONTROL __Y commands and describes the 
flow of execution following CTRL/Y interruptions. 
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Figure 7-2 Flow of Execution Following CTRL/Y Action 


DBA1 :[HIGGINS]FILES.COM 


* @FILES 


$ ON CONTROL-Y THEN GOTO CLEAN_UP 

CtrOT) O 


• 






$ TYPE STATUS.OUT i 1 0 

$ IF SSTATUS THEN DELETE STATUS.OUTi1 

$ EXIT 
$ CLEAN_UP: 

$ DELETE STATUS.OUT 5 1 
$ DELETE ».TMP5* 

$ EXIT 0 





DBA1:[HIGGINS] PRIV.COM 

* 0PRIV 


♦ 

CtrOT) 0 


$ ON CONTROL-Y THEN WRITE SYSSOUTPUT- 


"Interruption not allowed...continuing" 

Interruption not allowed 

. • • continuing 

$ TYPE STATUS.OUT 51 0 



$ IF SSTATUS THEN DELETE STATUS.OUT 51 


The CTRL/Y interrupt at 0 occurs during execution of the TYPE command, at 0 . Control is transferred to the label 

CLEAN_UP. After executing the routine, the command procedure exits, at 0 and returns control to the interactive 

command level. 

The CTRL/Y interrupt at 0 occurs during execution of the TYPE command, at 0 . The WRITE command specified in the 
ON command is executed. Then, the command procedure continues execution at the command following the interrupted 
command. 
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A CTRL/Y action can be specified in each active command level, and affects 
only the command level in which it is specified. Figure 7-3 illustrates what 
happens when CTRL/Y is pressed during the execution of a nested command 
procedure. 
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Figure 7-3 Default CTRL/Y Action for Nested Procedures 


$ 0SEARCH 


Ctrl77) Q 


CtrOY) 0 


CtrUY) 0 


DBA1 :[HIGGINS]SEARCH.COM 


$ ON CONTROL-Y THEN GOTO CLEAN_UP 


$ 0SUBSEARCH 
$ NEXT-STEP: 


* EXIT 

* CLEAN_UP: 


DBA1:[HIGGINS] SUBSEARCH.COM 


$ 0SUBSUB 


DBA1 :[HIGGINS] SUBSUB.COM 


$ ON CONTROL-Y THEN SHOW TIME 


$ EXIT 


0 If a CTRL/Y interrupt occurs while SEARCH.COM is executing, control is transferred to the label CLEAN_UP. 

0 If a CTRL/Y interrupt occurs while SUBSEARCH.COM is executing, control is transferred to the label NEXT—STEP in 
SEARCH.COM. Because no CTRL/Y action is specified in SUBSEARCH.COM, the procedure exits to previous com¬ 
mand level when a CTRL/Y interrupt occurs. 

© If a CTRL/Y interrupt occurs while SUBSUB.COM is executing, the SHOW TIME command is executed. 
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7.3.3 Disabling and Enabling CTRL/Y Interruptions 

The SET NOCONTROL=Y command disables CTRL/Y handling: that is, if a 
command procedure executes the SET NOCONTROL=Y command, pressing 
CTRL/Y has no effect. 

The SET NOCONTROL=Y command also cancels the current CTRL/Y action 
established with the ON CONTROL _Y command. To reestablish the default 
CTRL/Y action, use the following two commands: 

$ SET NOCONTROL=Y 
$ SET CONTROL=Y 
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The first command disables CTRL/Y handling and cancels the current ON 
CONTROL _Y action; the second command enables CTRL/Y handling. At 
this point, the default action is reinstated: if CTRL/Y is pressed during the 
execution of the procedure, the command interpreter prompts for a command 
at the CTRL/Y command level. 

You can use the SET NOCONTROL=Y command at any command level; it 
affects all command levels until the SET CONTROL=Y command reenables 
CTRL/Y handling. 

Note: The ON CONTROL _Y and SET NOCONTROL=Y commands are 
intended for special applications. DIGITAL does not recommend, 
in general, that you disable CTRL/Y interrupts. To exit from a 
nonterminating loop when CTRL/Y is disabled, you must delete the 
process from which the looping procedure is executing from another 
terminal. 
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Working with Batch Jobs 


A batch job consists of one or more command procedures that you execute 
from another process. To execute a batch job, use the SUBMIT command to 
place the job in a batch queue. A batch queue is a list of batch jobs waiting 
to execute. After the system places your job in the batch queue, you can 
continue using your terminal interactively. Thus, a batch job allows you to 
use your terminal for other work while the system executes your command 
procedure. 

The system creates a detached process to execute your batch job. To create 
the detached process, the system logs in using the information from your 
UAF record. The system executes the system login command procedure and 
your login command procedure, and then executes the command procedures 
in the batch job. As these procedures execute, output is written to a log file. 
When the batch job completes, you can print the log file or save it in one of 
your directories. 

You use batch jobs to execute command procedures under the following 
conditions: 

• The command procedure takes a long time to execute 

• You want to schedule the command procedure for execution after a 
specific time, such as after normal working hours 

• You want to execute the command procedure at a reduced priority, 
because it uses a disproportionate amount of system resources 

This chapter describes the following techniques for manipulating batch jobs. 

• Submitting batch jobs 

• Controlling batch job output 

• Controlling jobs in a batch queue 

• Restarting batch jobs 

• Synchronizing batch jobs 


Submitting a Batch Job 

Use the SUBMIT command to enter a command procedure into a batch queue, 
By default, the SUBMIT command places command procedures into a queue 
named SYS$BATCH. If you omit the file type when you submit a command 
procedure, the type defaults to COM. For example: 

$ SUBMIT UPDATE 

Job UPDATE (queue SYS$BATCH, entry 201) started on SYS$BATCH 
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8.1 Submitting a Batch Job 


This command creates a job called UPDATE that contains the command 
procedure UPDATE.COM. This job is entered in the queue SYS$BATCH and 
is assigned the entry number 201. (After a job has been submitted, you refer 
to it using the entry number.) The system message shows that SYS$BATCH 
has started to execute your job. 

When you submit a command procedure for batch execution, the system 
saves the complete file specification for the command procedure, including 
the version number. If you update a command procedure after you submit 
it, the batch job executes the version of the command procedure that you 
submitted, rather than the new version. 

Because your login defaults are not usually the defaults needed to access files 
mentioned in your command procedures, use one of the following methods 
to ensure that the correct files are accessed: 

• Use complete file specifications—When referring to a file in a command 
procedure or when passing a file to a command procedure, include the 
device and directory names as part of the file specification. 

• Use the SET DEFAULT command—Before referring to a file in a 
command procedure, use the SET DEFAULT command at the beginning 
of the command procedure to specify the proper device and directory. 

As a batch job executes, it writes output to a log file. By default, the log file 
has the same name as the command procedure you submit, with a file type 
of LOG. When the job is finished, the system prints the log file and deletes it 
from your directory. See Section 8.3.1 for information on saving log files. 


8.1.1 Checking for Batch Jobs in Your Login Command Procedure 

Each time you submit a batch job, the system executes your login command 
procedure. You can cause sections of your login command procedure to be 
included or omitted when you execute batch jobs by using the F$MODE() 
lexical function to test for batch jobs. 

For example, you might have a section in your login command procedure that 
includes commands, logical names, and symbols that you use exclusively for 
batch jobs. You might label this section BATCH-COMMANDS, then include 
the following command at the beginning of your login command procedure: 

IF F$M0DE() .EQS. "BATCH" THEN GOTO BATCH.COMMANDS 


To prevent the system from executing any commands in your login command 
procedure when you submit a batch job, place the following command at the 
beginning of the procedure: 

IF F$M0DE() .NES. "INTERACTIVE" THEN EXIT 

You can place this command anywhere in your login command procedure. 
When you submit a batch job, the system executes your login command 
procedure only to the point at which the preceding command is placed. 
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8.1.2 Submitting Multiple Command Procedures 

When you enter the SUBMIT command, you can specify several command 
procedures to be executed in one job. For example: 

$ SUBMIT UPDATE,SORT 

Job UPDATE (queue SYS$BATCH, entry 207) started on SYS$BATCH 

This SUBMIT command creates a batch job that executes UPDATE.COM, 
then SORT.COM. Unless you specify a name with the /NAME qualifier, the 
SUBMIT command uses the name of the first command procedure as the job 
name. Note that if an error causes any command procedure in a job to exit, 
the entire job terminates. 

When a batch job executes, the operating context of the first procedure 
(UPDATE.COM) is not preserved for the second procedure (SORT.COM). 
That is, the system deletes local symbols created by UPDATE.COM before 
SORT.COM executes. Global symbols, however, are preserved. 

You cannot specify different parameters for individual command procedures 
within a single job. The following example passes the same two parameters 
to UPDATE.COM and SORT.COM: 

$ SUBMIT UPDATE. SORT/PARAMETERS = - 

_$ (DISKI:[ACCOUNT.BILLS]DATA.DAT, DISK2:[ACCOUNT]NAME.DAT) 

Job UPDATE (queue SYS$BATCH, ENTRY 208) started on SYSSBATCH 


8.1.3 Controlling a Batch Job 

Use qualifiers to the SUBMIT command to control how a batch job is 

submitted. The following list describes some common operations and the 

qualifiers you use to perform them. For a complete list of qualifiers to the 

SUBMIT command, see the VMS DCL Dictionary. 

You can do the following when you submit a batch job: 

• Name the job—Use the /NAME qualifier to specify a name for the batch 
job. Otherwise the job name defaults to the file name of the first (or only) 
command procedure in the job. 

• Specify the time when the batch job starts to execute—Use the /AFTER 
qualifier to specify a time after which the job can be executed. When you 
use /AFTER, the job remains in the batch queue until the specified time; 
then it executes. To hold a job in the queue until you explicitly release 
it, use the /HOLD qualifier. (To release a job that is being held, use the 
SET ENTRY/RELEASE command.) 

• Request notification of job completion—Use the /NOTIFY qualifier to 
have the system send a message to your terminal when the batch job 
finishes executing. 

• Send the job to a specific queue—Use the /QUEUE qualifier to send a 
batch job to a queue other than SYS$BATCH. To execute a command 
procedure that is located on a remote node, use the /REMOTE qualifier. 
This sends the job to SYS$BATCH at the remote node. 

• Specify execution characteristics—You can specify execution 
characteristics such as working set default, working set extent, working 
set size, job scheduling priority, and CPU time limit. 
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• Pass parameters—Use the /PARAMETERS qualifier to pass parameters to 
a batch job. 

• Save the log file—Use the /NOPRINTER or /KEEP qualifiers to save a 
batch job log file. See Section 8.3 for information on controlling batch job 
output. 

• Make the batch job restartable—Use the /RESTART qualifier to enable 
you to restart the job if the system fails while the job is executing. See 
Section 8.5 for information on restarting batch jobs. 

If you submit jobs frequently using the same qualifiers, place a global symbol 
for the SUBMIT command string in your login command procedure. For 
example: 

$ SUBMIT == "SUBMIT/NOTIFY/NOPRINTER" 


8.2 Passing Data to Batch Jobs 

The default input stream (SYS$INPUT) for a batch job is the command 
procedure that is being executed. Because a detached process is executing the 
batch job, you cannot redefine SYS$INPUT to the terminal (as you can with 
command procedures that you execute interactively.) This means that you 
cannot enter input to a command procedure executing in a batch job from 
your terminal. Therefore, pass input to a batch job in one of the following 
ways: 

• Include the data in the command procedure itself 

• Temporarily define SYS$INPUT as a file 

• Pass parameters to the command procedure 

To include data in a command procedure, place the data on the lines after the 
command or image. For example: 

$! Execute AVERAGE.EXE 

$ RUN AVERAGE 

647 

899 

532 

401 

$ EXIT 

To define SYS$INPUT temporarily as a file, use the DEFINE/USER__MODE 
command. For example: 

$ DEFINE/USER.MODE SYS$INPUT STATS.DAT 
$ RUN AVERAGE 
$ EXIT 

To pass parameters to a command procedure, use the /PARAMETERS 
qualifier when you submit the batch job. For example: 

$ SUBMIT/PARAMETERS=(DISKI:[PAYROLL]EMPLOYEES.DAT) CHECKS 
Job CHECKS (queue SYS$BATCH, entry 209) started on SYS$BATCH 

Note that you cannot specify different parameters for individual command 
procedures within a single job; use separate SUBMIT commands if you need 
to pass different groups of parameters. 
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Note: The SHOW QUEUE/FULL command displays full information about jobs 
in a batch queue. This display includes any parameters you pass to the 
procedure. Therefore, do not pass confidential information (such as a 
password) to a batch job. 


8.3 Batch Job Output 

If you use the SUBMIT command without any qualifiers that change the log 
file name, the log file has the same name as the first command procedure 
in the batch job, and a file type of LOG. The system writes output to the 
log file once each minute. (To specify a different time interval, include the 
SET OUTPUT-RATE command in your command procedure.) When the job 
finishes, the system sends the log file to the default system print queue and 
deletes it from your directory after it prints unless you specify otherwise. 
Section 8.3.1 describes how to save the log file or prevent it from printing 
automatically. 

The batch job log file includes all output to SYS$OUTPUT and SYS$ERROR. 
It also includes, by default, all command lines executed in the command 
procedure. To prevent the command lines from being printed, use either the 
SET NOVERIFY command or the F$VERIFY lexical function in your command 
procedure. When the job completes, the system writes job termination 
information (using the long form of the system logout message) to the log file. 

When a batch job fails to complete successfully, you can examine the log file 
to determine the point at which the command procedure failed and the error 
status that caused the failure. 


8.3.1 Saving the Log File 

To save the log file, use either the /KEEP or the /NOPRINTER qualifier. 
The /KEEP qualifier saves the log file after it is printed; the /NOPRINTER 
qualifier saves the log without printing it. (If you specify neither of these 
qualifiers, the default action occurs. The log file is queued to the default 
print queue SYS$PRINT and is deleted after it prints.) The /KEEP and 
/NOPRINTER qualifiers save the log file in your default login directory. The 
log file has the same name as the first command procedure in the batch job, 
and a file type of LOG. To specify an alternate file name or directory name, 
or both, use the /LOG—FILE qualifier. To rename and save the log file, you 
must use /LOG_FILE plus either /KEEP or /NOPRINTER. For example: 

$ SUBMIT/L0G_FILE=DISK2:[JONES.RESULTS]/NOPRINTER - 
_$ DISK2: [JONES.RESULTS]UPDATE 


8.3.2 Reading the Log File 

You can use the TYPE command to read the log file to determine how much 
of a batch job has completed. However, if you attempt to display the log file 
while the system is writing to it, you receive a message indicating that the file 
is locked by another user. If this occurs, wait a few seconds and try again. 
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8.3.3 Including All Command Output in the Batch Job Log 

Typically, a batch job command procedure that compiles, links, and executes 
a program creates additional printed output such as a compiler listing or a 
linker map. To produce printed copies of these files, a batch job command 
procedure can contain the PRINT commands necessary to print them, as in 
the following example: 

$ FORTRAN BIGCOMP 
$ PRINT BIGCOMP 
$ LINK/MAP/FULL BIGCOMP 
$ PRINT BIGCOMP.MAP 

When this command procedure completes processing, there are three separate 
output listings: the batch job log, the compiler listing, and the linker map. 

If you want a batch job log to contain all output from the command 
procedure, including printed listings of compiler or linker output files, you 
can do either of the following: 

• Use the TYPE command instead of the PRINT command in the command 
procedure. The TYPE command writes to SYS$OUTPUT. (In a batch job, 
SYS$OUTPUT is equated to the batch job log file.) 

• Use qualifiers on appropriate commands to direct the output to 
SYSSOUTPUT. 

The following example shows the second technique: 

$ FORTRAN/LIST=SYS$OUTPUT BIGCOMP 
$ LINK/MAP=SYS$OUTPUT/FULL BIGCOMP 

When these commands are executed in a batch job, the output files from the 
compiler and the linker are written directly to the log file. Note that if you 
use this technique, the output files are not saved on disk unless you save the 
log file. 


8.4 Controlling Jobs in a Batch Queue 

Once a job has been entered in a batch job queue, you can monitor its status 
with the SHOW ENTRY command or the SHOW QUEUE command. The 
SHOW ENTRY command works as follows: 

$ SUBMIT EXCHAN.DAT 

Job EXCHAN (queue SYS$BATCH entry 999) started on SYS$BATCH 
$ SHOW ENTRY 999 

Jobname Username Entry Status 


EXCHAN BLASS 999 Executing 

On batch queue SYS$BATCH 

The SHOW QUEUE command works as follows: 

$ SUBMIT/NOPRINTER/PARAMETER=STATS.DAT UPDATE 

Job UPDATE (queue SYS$BATCH entry 1080) started on BOSTON.BATCH 

$ SHOW QUEUE BOSTON.BATCH 

Batch queue BOSTON.BATCH on BOSTON:: 

Jobname Username Entry Status 


UPDATE ODONNELL 1080 Executing 
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If you had no jobs in the queue, the system would display the following 
message: 

$ SHOW QUEUE BOSTON.BATCH 

Batch queue B0ST0N_BATCH, on BOSTON:: 

To see complete information on your jobs, use the /FULL qualifier to the 
SHOW ENTRY or SHOW QUEUE command: 

$ SHOW ENTRY/FULL 999 

Jobname Username Entry Status 


EXCHAN BLASS 999 Executing 

On batch queue B0ST0N_BATCH 
Submitted 23-N0V-1987 13:12 /PRI0RITY=100 
WRKD:[BLASS]EXCHAN.DAT;3 


$ SHOW QUEUE/FULL B0ST0N_BATCH 

Job UPDATE (queue B0ST0N_BATCH, entry 1080) started on BOSTON.BATCH 
Batch queue BOSTON.BATCH, on BOSTON:: 

/BASE_PRIORITY=3 /J0B_LIMIT=5 /0WNER=[EXEC] /PR0TECTI0N=(S:E,0:D,G:R,W:W) 

Jobname Username Entry Status 


UPDATE ODONNELL 1080 Executing 

Submitted 15-FEB-1984 10:46 /KEEP /PARAM=("STATS.DAT") /NOPRINTER /PRI0=4 
_B0ST0N$DQA2:[ODONNELL]TEMP.COM;1 (executing) 

The /FULL qualifier displays statistics about BOSTON—BATCH and 
characteristics associated with your job. 

To see the status of other jobs in the queue, use the SHOW QUEUE/ALL 
command. For example: 


$ SHOW QUEUE/ALL BOSTON.BATCH 
Batch queue B0ST0N_BATCH on BOSTON:: 

Jobname Username Entry Status 


no privilege 
no privilege 


UPDATE 


ODONNELL 


923 Executing 

939 Holding until 27-DEC-1987 19:00 
1080 Executing 


Note that unless you are a privileged user, you may be able to obtain 
information only about jobs that have been submitted under your account. 
See the VMS DCL Dictionary for more information on the SHOW ENTRY and 
SHOW QUEUE commands. 


8.4.1 Changing Job Characteristics 

After a job has been submitted to the queue but before the job starts to 
execute, you can use the SET ENTRY or the SET QUEUE/ENTRY command 
with the appropriate qualifiers to change characteristics associated with the 
job. For example, to change the name of a batch job while it is pending in a 
batch queue, you can enter either of the following commands: 

$ SET QUEUE/ENTRY=209/NAME=NEW_NAME SYSSBATCH 
$ SET ENTRY 209 /NAME=NEW_NAME 

Both of these commands change the name of the job number 209 to NEW_ 
NAME. 
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8.4 Controlling Jobs in a Batch Queue 


The following list contains some of the changes you can make with the SET 
ENTRY or SET QUEUE/ENTRY commands; for a complete list of qualifiers 
see the VMS DCL Dictionary. Note that most of the qualifiers allowed with 
the SUBMIT command can also be used with SET ENTRY and the SET 
QUEUE/ENTRY commands. 

You can make the following changes: 

• Delay processing of a job—Use the /AFTER qualifier to specify a time 
after which the job can be executed; use the /HOLD qualifier to hold a 
job until you explicitly release it. 

• Release a job—Use the /NOHOLD or /RELEASE qualifier to release a 
job that was submitted with the /HOLD or /AFTER qualifiers. 

• Send a job to a different queue—Use the /REQUEUE qualifier to change 
the queue on which the job will execute. 

• Change execution characteristics—You can change execution 
characteristics such as working set default, working set extent, working 
set size, job scheduling priority, and CPU time limit. 

• Change the parameters to be passed to a job—Use the /PARAMETERS 
qualifier to change the parameters. 


8.4.2 Deleting and Stopping Batch Jobs 

You can delete batch jobs before or during execution. To delete an entry 
that is pending or already executing in a batch queue, use the DELETE 
/ENTRY command. For example, the following command deletes a job in 
SYS$BATCH: 

$ DELETE/ENTRY=210 SYS$BATCH 

You need special privileges to delete a job that you did not submit. See the 
VMS DCL Dictionary for more information. 

When a job terminates as a result of a DELETE/ENTRY command, the log 
file is neither printed nor deleted from your directory. 

When you terminate a job using the DELETE/ENTRY command, it is handled 
as an abnormal termination because the operating system's normal job 
termination activity is preempted. As a result, the batch job log does not, 
for example, contain the standard logout message that summarizes job time 
and accounting information. Termination that results either from an explicit 
EXIT command or STOP command or the implicit execution of either of these 
commands (as the result of the current ON condition), however, is considered 
normal termination. The operating system performs proper run-down and 
accounting procedures after a normal termination. 
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8.5 Restarting Batch Jobs 

If the system fails while your batch job is executing, your job does not 
complete. When the system recovers and the queue is restarted, your job is 
aborted and the next job in the queue is executed. However, by specifying 
the /RESTART qualifier when you submit a job, you indicate that the system 
should reexecute the job if the system crashes before the job completes. 

By default, a batch job is restarted beginning with the first line. However, 
you can specify a different starting point so that you do not reexecute parts of 
the job that have completed successfully. To do this, follow these steps: 

• Begin each possible starting point in the procedure with a label. After the 
label, use the SET RESTART-VALUE command to set the restarting point 
to that label. If the batch job is interrupted by a system crash and is then 
restarted, the SET RESTART-VALUE command assigns the appropriate 
label name to the global symbol BATCH$RESTART. 

• At the beginning of the procedure, test the value of the symbol 

$ RESTART. ($RESTART is a global symbol that the system maintains 
for you. $RESTART has the value "TRUE" if one of your batch jobs 
was restarted after it was interrupted by a system crash. Otherwise, 
$RESTART has the value "FALSE".) If $RESTART is true, execute a 
GOTO statement using BATCH$RESTART as the transfer label. 

The following command procedure shows how to use restart values in a batch 
job. 

$ ! set default to the directory containing 
$ ! the file to be updated and sorted 
$ SET DEFAULT DISKI:[ACCOUNTS.DATA84] 

$ 

$ ! check for restarting 
$ IF SRESTART THEN GOTO *BATCH$RESTART * 

$ 

$ UPDATE.FILE: 

$ SET RESTART.VALUE = UPDATE.FILE 


$ SORT.FILE: 

$ SET RESTART.VALUE = SORT.FILE 


EXIT 

To submit this command procedure as a batch job that can be restarted, use 
the /RESTART qualifier when you submit the job. If you restart a job that 
was interrupted by a system crash, the job starts executing in the section 
where it was interrupted. For example, if the job is interrupted during the 
SORT—FILE routine, it starts executing at the label SORT-FILE when it is 
restarted. 

In addition to restarting a job after a system crash, you can also restart a job 
after you explicitly stop the job. To stop a job and then restart it on the same 
or a different queue, use the STOP/QUEUE/REQUEUE/ENTRY command. 
For example: 

$ STOP/QUEUE/REQUEUE/ENTRY=212 SYS$BATCH 
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This command stops job 212 on SYS$BATCH, and requeues it on 
SYS$BATCH. (To enter this command, job 212 must have been submitted 
with the /RESTART qualifier.) When the batch job executes the second time, 
the system uses the global symbol BATCH$RESTART to determine where to 
begin executing the job. 


8.6 Synchronizing Batch Job Execution 

You can use the SYNCHRONIZE and WAIT commands within a command 
procedure to place the procedure in a wait state. The SYNCHRONIZE 
command causes the procedure to wait for the completion of a specified job, 
while the WAIT command causes the procedure to wait for a specified period 
of time to elapse. For example, if two jobs are submitted concurrently to 
perform cooperative functions, one job can contain the following command: 

$ SYNCHRONIZE BATCH25 

After this command is executed, the command procedure cannot continue 
execution until the job identified by the job name BATCH25 completes 
execution. Figure 8-1 shows an example of command procedures that are 
submitted for concurrent execution, but which must be synchronized for 
proper execution. Each procedure compiles a large source program. 

Figure 8-1 Synchronizing Batch Job Execution 


$ SUBMIT MAINCOMP 
JOB 314 entered 
♦SUBMIT MINCOMP 
JOB 315 entered 


queue SYS$BATCH 0 
queue SYS$BATCH 0 


© 


DBA1 :[HIGGINS] MAINCOMP.COM 


$ FORTRAN ALPHA/LIST 
$ SYNCHRONIZE MINCOMP 
$ LINK/MAP/FULL ALPHA,BETA 
$ EXIT 


DBA1:[HIGGINS] MINCOMP.COM 


$ FORTRAN BETA/LIST 
♦ EXIT 


0 Individual SUBMIT commands are required to submit two separate jobs. Two separate processes will be created. 

0 After the FORTRAN command is executed, the SYNCHRONIZE command is executed. If job 315 has completed 
execution, job 314 continues with the next command. However, job 314 will not execute the next command, if job 315 
is either current or pending. 

ZK-832-82 


If you specify a job name with the SYNCHRONIZE command, the jobs to be 
synchronized must have the same group number in their user identification 
codes (UICs). To synchronize jobs that have different group numbers, you 
must specify the job entry number with the SYNCHRONIZE command rather 
than the job name. For example: 

$ SYNCHR0NIZE/ENTRY=454 

This SYNCHRONIZE command places the current command procedure in a 
wait state until job 454 completes. 
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8.6 Synchronizing Batch Job Execution 


The WAIT command is useful for command procedures that must have access 
to a shared system resource such as a disk or tape drive. The following 
example shows a procedure that requests the allocation of a tape drive; if the 
command does not complete successfully, the procedure places itself in a wait 
state. After a five-minute interval, it retries the request: 

$ TRY: 

$ ALLOCATE DM: RK: 

$ IF SSTATUS THEN GOTO OKAY 

$ WAIT 00:05 

$ GOTO TRY 

$ OKAY: 

$ REQUEST/REPLY/T0=DISKS - 

"Please mount BACK_UP_GMB on * >F$TRNLNM("RK") ’" 


The IF command following the ALLOCATE request checks the value of 
SSTATUS. If the value of SSTATUS indicates successful completion, the 
command procedure continues. Otherwise, the procedure executes the WAIT 
command; the WAIT command specifies a time interval of five minutes. After 
waiting five minutes, the next command, GOTO, is executed, and the request 
is repeated. This procedure continues looping and attempting to allocate a 
device until it succeeds or until the batch job is deleted or stopped. 
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This appendix contains complete command procedures that demonstrate the 
concepts and techniques discussed in this book. Each section in this appendix 
discusses one command procedure and contains the following information: 

• The name of the procedure 

• A listing of the procedure 

• Notes that explain concepts or techniques used by the procedure 

• The results of a sample execution of the procedure 

The command procedures are as follows: 

CONVERT.COM 

Section A.l contains the sample command procedure CONVERT.COM. This 
procedure converts an absolute time (for a time in the future) to a delta time. 
Therefore, the procedure determines the time between the current time and 
the time that you specify. The procedure illustrates the use of the F$TIME 
and F$CVTIME lexical functions and the use of assignment statements to 
perform arithmetic calculations and to concatenate symbol values. 

REMINDER.COM 

Section A.2 contains the sample command procedure REMINDER.COM. This 
procedure displays a reminder message on your terminal at a specified time. 
The procedure prompts for the time you want the message to be displayed, 
and for the text of the message. The procedure uses CONVERT.COM to 
convert the time to a delta time. The procedure then spawns a subprocess 
that waits until the specified time and displays your reminder message. The 
procedure illustrates the use of the F$ENVIRONMENT, F$VERIFY, and 
F$GETDVI functions. 

DIR.COM 

Section A.3 contains the sample command procedure DIR.COM. This 
procedure imitates the DCL command DIRECTORY/SIZE=ALL/D ATE, 
displaying the block size (used and allocated) and creation date of the 
specified files. It illustrates use of the F$PARSE, F$SEARCH, F$FILE_ 
ATTRIBUTES, and F$FAO lexical functions. 

SYS.COM 

Section A.4 contains the sample command procedure SYS.COM. This 
procedure returns statistics about processes in the current process list. If 
the current process has GROUP privilege, the procedure returns statistics for 
all processes in the group. If the current process has WORLD privilege, the 
procedure returns statistics for all processes on the system. If the current 
process has neither GROUP nor WORLD privilege, the procedure returns 
statistics for the current process. This procedure illustrates use of the F$PID, 
F$EXTRACT, and F$GETJPI lexical functions. 
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GETPARMS.COM 

Section A.5 contains the sample command procedure GETPARMS.COM. 

This procedure returns the number of parameters passed to a procedure. 
GETPARMS.COM can be called from another procedure to determine how 
many parameters were passed to the calling procedure. 

EDITALL.COM 

Section A.6 contains the sample command procedure EDITALL.COM. This 
procedure invokes the EDT editor repeatedly to edit a group of files with 
the same file type. This procedure illustrates how to use lexical functions to 
extract file names from columnar output. It also illustrates a way to redefine 
the input stream for a program invoked within a command procedure. 

FORTUSER.COM 

Section A.7 contains the sample command procedure FORTUSER.COM. 

This example of a system-defined login command procedure provides a 
controlled terminal environment for an interactive user who creates, compiles, 
and executes FORTRAN programs. If a user logs into a captive account 
where FORTUSER.COM is listed as the login command procedure, then the 
user can execute only the commands accepted by FORTUSER.COM. This 
procedure also illustrates using lexical functions to step through an option 
table, comparing a user-entered command with a list of valid commands. 

LISTER.COM 

Section A.8 contains the sample command procedure LISTER.COM. This 
procedure prompts for input data, formats the data in columns, and sorts 
it into an output file. This procedure illustrates the READ and WRITE 
commands, as well as the character substring overlay format of an assignment 
statement. 

CALC.COM 

Section A.9 contains the sample command procedure CALC.COM. This 
procedure performs arithmetic calculations and converts the resulting value to 
hexadecimal and decimal values. 

BATCH.COM 

Section A.10 contains the sample command procedure BATCH.COM. This 
procedure accepts a command string, a command procedure, or a list of 
commands and then executes these commands as a batch job. 

COMPILE_FILE.COM 

Section A.ll contains the sample command procedure COMPILE_FILE.COM. 
This procedure compiles, links, and runs a file written in PASCAL or 
FORTRAN. It prompts for a file to process, and determines if the file type 
is PAS or FOR. If the file type is not PAS or FOR, or if the file does not exist 
in the current default directory, the command procedure outputs appropriate 
error messages. This command procedure illustrates the use of the IF-THEN- 
ELSE language construct. 
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A.1 


CONVERT.COM 


$ 

$ 

$ 

$ 

$ 

$ 
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$ 

$ 
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$ 

$ 

$ 

$ 
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$ 

$ 

$ 

$ 

$ 

$ 

$ 
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$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 


! Procedure to convert an absolute time to a delta time. 

! The delta time is returned as the global symbol WAIT_TIME. 

! PI is the time to be converted. 

! P2 is an optional parameter - SHOW - that causes the 
! procedure to display WAIT_TIME before exiting 

i 

! Check for inquiry 

j 

IF PI .EQS. "?" .OR. PI .EQS. "" THEN GOTO TELL O 
| 

! Verify the parameter: hours must be less than 24 
! minutes must be less than 60 

! time string must contain only hours 

! and minutes 

i 

! Change error and message handling to 
! use message at BADTIME 
! 

ON WARNING THEN GOTO BADTIME © 

SAVE.MESSAGE = F$ENVIRONMENT("MESSAGE") 

SET MESSAGE/NOFACILITY/NOIDENTIFICATION/NOSEVERITY/NOTEXT 
TEMP = F$CVTIME(P1) 

j 

! Restore default error handling and message format 
ON ERROR THEN EXIT 
SET MESSAGE *SAVE.MESSAGE * 

i 

IF F$LENGTH(P1) .NE. 5 .OR. - © 

F$LOCATE(":",P1) .NE. 2 - 
THEN GOTO BADTIME 

I 

! Get the current time 

j 

TIME = F$TIME() © 

! 

! Extract the hour and minute fields from both the 
! value (TIME) and the future time (PI) 

! 

MINUTES = F$CVTIME(TIME."ABSOLUTE"."MINUTE") 

HOURS = F$CVTIME(TIME,"ABSOLUTE"."HOUR") 

FUTURE.MINUTES = F$CVTIME(P1."ABSOLUTE","MINUTE") 

FUTURE.HOURS = F$CVTIME(PI,"ABSOLUTE","HOUR") 

j 
j 

! Convert both time values to minutes 
! Note the implicit string to integer conversion being performed 

i 

CURRENT.TIME = H0URS*60 + MINUTES © 

FUTURE.TIME = FUTURE_H0URS*60 + FUTURE_MINUTES 

j 

! Compute difference between the future time and the current time 
! (in minutes) 

i 

i 

MINUTES_TO_WAIT = FUTURE.TIME - CURRENT.TIME © 

J 

! If the result is less than 0 the specified time is assumed to be 
! for the next day; more calculation is required. 

i 

IF MINUTES_TO_WAIT .LT. 0 THEN - © 

MINUTES_TO_WAIT = 24*60 + FUTURE.TIME - CURRENT.TIME 


current time 


! Current minutes © 

! Current hours 
! Minutes in future time 
! Hours in future time 
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$ ! 

$ ! Start looping to determine the value in hours and minutes from 
$ ! the value expressed all in minutes 
$ ! 

$ HOURS.TO.WAIT = 0 

$ HOURS.TO.WAIT.LOOP: © 

$ IF MINUTES.TO.WAIT .LT. 60 THEN GOTO FINISH.COMPUTE 

$ MINUTES.TO.WAIT = MINUTES.TO.WAIT - 60 

$ HOURS.TO.WAIT = HOURS.TO.WAIT + 1 

$ GOTO HOURS.TO.WAIT.LOOP 

$ FINISH.COMPUTE: 

$ ! 

$ ! Construct the delta time string in the proper format 
$ ! 

$ WAIT.TIME == F$STRING(HOURS.TO.WAIT)+ + F$STRING(MINUTES.TO.WAIT)- © 

+ ":00.00" 

$ ! 

$ ! Examine the second parameter 

$ ! 

$ IF P2 .EQS. "SHOW" THEN SHOW SYMBOL WAIT.TIME © 

$ ! 

$ ! Normal exit 

$ ! 

$ EXIT 

$ ! 

$ BADTIME: © 

$ ! Exit taken if first parameter is not formatted correctly 
$ ! EXIT command returns but does not display error status 
$ ! 

$ SET MESSAGE *SAVE.MESSAGE * 

$ WRITE SYS$OUTPUT "Invalid time value: ",P1,", format must be hh:mm" 

$ WRITE SYS$OUTPUT "Hours must be less than 24; minutes must be less than 60" 
$ EXIT # /.X10000000 
$ ! 

$ ! 

$ TELL: © 

$ ! Display message and exit if user enters inquiry or enters 
$ ! an illegal parameter 
$ ! 

$ TYPE SYS$INPUT 

This procedure converts an absolute time value to 
a delta time value. The absolute time must be in 
the form hh:mm and must indicate a time in the future. 

On return, the global symbol WAIT.TIME contains the 
converted time value. If you enter the keyword SHOW 
as the second parameter, the procedure displays the 
resulting value in the output stream. To invoke this 
procedure, use the following syntax: 

OCONVERT hh:mm [SHOW] 

$ EXIT 


Notes 

© The procedure checks whether the parameter was omitted or whether the 
value entered for a parameter is the question mark character (?). In either 
case, the procedure branches to the label TELL. 

© The procedure uses the F$CVTIME function to verify that the time value 
is a valid 24-hour clock time; the F$CVTIME returns a warning message if 
the input time is not valid. Therefore, the procedure changes the default 
ON action to direct control to the label BADTIME if the F$CVTIME 
function returns an error. 
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The procedure uses the F$ENVIRONMENT function to save the current 
message setting, and then sets the message format so that no warning 
or error messages are displayed. After checking the time values, the 
procedure restores the default ON condition and message format. 

© The procedure checks the format of the parameter. It must be a time 
value in the format: 

hh:mm 

The IF command checks (1) that the length of the entered value is 5 
characters and (2) that the third character (offset of 2) is a colon. The 
IF command contains the logical OR operator: if either expression is 
true (that is, if the length is not 5 or if there is not a colon in the third 
character position), the procedure branches to the label BADTIME. 

© The F$TIME lexical function places the current time value in the symbol 
TIME. 

© The F$CVTIME function extracts the "minute" and "hour" fields from the 
current time (saved in the symbol TIME). Then the F$CVTIME function 
extracts the "minute" and "hour" fields from the time you want to convert. 

© These assignment statements convert the current and future times to 
minutes. When you use the symbols MINUTES, HOURS, FUTURE— 
HOURS, and FUTURE—MINUTES in the assignment statements, the 
system automatically converts these values to integers. 

O The procedure then subtracts the current time (in minutes) from the future 
time (in minutes). 

© If the result is less than 0, the future time is interpreted as being on the 
next day. In this case, the procedure adds 24 hours to the future time, 
and then subtracts the current time. 

© The procedure enters a loop in which it calculates, from the value of 
MINUTES—TO—WAIT, the number of hours. Each time through the 
loop, it checks whether MINUTES—TO—WAIT is greater than 60. If so, it 
subtracts 60 from MINUTES—TO—WAIT and adds 1 to the accumulator 
for the number of hours (HOURS—TO—WAIT). 

© When the procedure exits from the loop, it concatenates the hours and 
minutes values into a time string. The symbols HOURS—'TO—WAIT and 
MINUTES—TO_WAIT are replaced by their character string equivalents 
and separated with an intervening colon. The resulting string is assigned 
to the symbol WAIT—TIME, which holds the delta time value for the 
future time. WAIT—TIME is defined as a global symbol so that it is not 
deleted when the procedure CONVERT.COM exits. 

© If a second parameter, SHOW, was entered, the procedure displays the 
resulting time value. Otherwise, it exits. 

© At the label BADTIME, the procedure displays an error message that 
shows the incorrect value entered as well as the format it requires. After 
issuing the error message, CONVERT.COM exits. The EXIT command 
returns an error status in which the high order digit is set to 1. This 
suppresses the display of an error message. 

The procedure explicitly specifies an error status with the EXIT command, 
so you can execute CONVERT.COM from within another procedure. 
When CONVERT.COM completes, the calling procedure can determine 
whether a time was successfully translated. 
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© At the label TELL, the procedure displays information about what 
the procedure does. The TYPE command displays the lines listed in 
SYS$INPUT, the input data stream. 

Sample Execution 

$ SHOW TIME 
10-JUN-1984 10:38:26 
$ ^CONVERT 12:00 SHOW 

WAIT.TIME = "1:22:00.00" 

The SHOW TIME command displays the current date and time. 
CONVERT.COM is executed with the parameters 12:00 and SHOW. The 
procedure converts the absolute time 12:00 to a delta time value and displays 
it on the terminal. 


A.2 


REMINDER.COM 


$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 
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$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 

$ 


! Procedure to obtain a reminder message and display this 
! message on your terminal at the time you specify. 

! 

! Save current states for procedure and image verification 
! Turn verification off for duration of procedure 

SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE") O 
SAVE_VERIFY_PROC = F$VERIFY(0) 

I 

! Places the current process in a wait state until a specified 
! absolute time. Then, it rings the bell on the terminal and 
! displays a message. 

i 

! Prompt for absolute time 


GET_TIME: 

INQUIRE REMINDER_TIME "Enter time to send reminder (hh:mm)" © 
INQUIRE MESSAGE.TEXT "Enter message" 

I 

! Call the CONVERT.COM procedure to convert the absolute time 
! to a delta time 

I 

0DISK2:[JONES.TOOLS]CONVERT ’REMINDER_TIME’ © 

IF .NOT. $STATUS THEN GOTO BADTIME 


Create a command file that will be executed 
in a subprocess. The subprocess will wait until 
the specified time and then display your message 
at the terminal. If you are working at a DEC_CRT 
terminal, the message has double size blinking 
characters. Otherwise, the message has normal letters. 
In either case, the terminal bell rings when the 
message is displayed. 


CREATE WAKEUP.COM 
DECK 

WAIT ’WAIT_TIME’ 

IF F$GETDVI("SYS$OUTPUT" 
BELL [0,7] = %X07 


© 

! Lines starting with $ 

0 

,"TT_DECCRT") .NES. "TRUE" THEN 
! Create symbol to ring 


are data lines 

GOTO OTHER_TERM 
the bell 
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$ • 

$ DEC_CRT_ONLY: 

$ ! Create symbols to set special graphics (for DEC_CRT terminals only) 

$ ! 

$ SET_FLASH = "<ESC>[1;5m" ! Turn on blinking characters 

$ SET_NOFLASH = "<ESC>[Om" ! Turn off blinking characters 

$ TOP = "<ESC>#3" ! Double size characters (top portion) 

$ BOT = "<ESC>#4" ! Double size characters (bottom portion) 

$ ! 

$ ! Write double size, blinking message to the terminal and ring the bell 
$ ! 

$ WRITE SYS$OUTPUT BELL, SET.FLASH, TOP, MESSAGE.TEXT 

$ WRITE SYS$OUTPUT BELL. BOT, MESSAGE.TEXT 

$ WRITE SYS$OUTPUT F$TIME(), SET.NOFLASH 

$ GOTO CLEAN.UP 

$ ! 

$ OTHER.TERM: 

$ WRITE SYS$OUTPUT BELL.MESSAGE.TEXT 

$ WRITE SYS$OUTPUT F$TIME() 

$ ! 

$ CLEANJJP: 

$ DELETE WAKEUP.COM;* 

$ EOD 
$ ! 

$ ! Now continue executing commands. 

$ ! 

$ SPAWN/NOWAIT/INPUT=WAKEUP.COM © 

$ END: O 

$ ! Restore verification 

$ SAVE_VERIFY_PROC = F$VERIFY(SAVE_VERIFY_PROC, SAVE_VERIFY_IMAGE) 

$ EXIT 

$ • 

$ BADTIME: 

$ WRITE SYS$OUTPUT "Time must be entered as hh:mm" 

$ GOTO GET.TIME 

Notes 

O The procedure uses the F$ENVIRONMENT function to save the image 
verification setting in the symbol SAVE—VERIFY—IMAGE. Next, the 
procedure uses the F$VERIFY function to save the procedure verification 
setting in the symbol SAVE—VERIFY—PROC. The F$VERIFY function also 
turns both types of verification off. 

© The procedure uses the INQUIRE command to prompt for the time when 
the reminder message should be sent. This value is used as input to the 
procedure CONVERT.COM. The procedure also prompts for the text of 
the message. 

© The procedure executes a nested procedure, CONVERT.COM. Be sure to 
specify the disk and directory as part of the file specification; this ensures 
that the system can locate CONVERT.COM regardless of the directory 
from which you execute REMINDER.COM. 

CONVERT.COM converts your reminder to a delta time, and returns this 
time in the global symbol WAIT—TIME. This delta time indicates the time 
interval from the current time until the time when the message should be 
sent. If CONVERT.COM returns an error, the procedure branches to the 
label BADTIME. 
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© The procedure uses the CREATE command to create a new procedure, 
WAKEUP.COM. This procedure is executed from within a subprocess. To 
allow the CREATE command to read lines that begin with dollar signs, 
use the DECK and EOD commands to surround the input for the CREATE 
command. Therefore, all lines between the DECK and EOD commands 
are written to WAKEUP.COM. 

© WAKEUP.COM performs the following tasks: 

• It waits until the time indicated by the symbol WAIT_TIME. 

• It creates the symbol BELL to ring the terminal bell. 

• It determines whether the terminal is a DEC—CRT terminal and can 
accept escape sequences to display double size, blinking characters. 
(To see whether you have a DEC—CRT terminal, enter the SHOW 
TERMINAL command and see whether this characteristic is listed.) 

• If the terminal is a DEC—CRT terminal, then the procedure defines 
the symbols SET—FLASH, TOP, and BOT. These symbols cause 
the terminal to use flashing, double-size characters. The procedure 
also defines the symbol SET—NOFLASH to return the terminal to 
its normal state. To enter the escape character ( <ESC> ) when you 
create these definitions using the EDT editor, press the ESC key twice. 

After defining these symbols, the procedure writes three lines to the 
terminal. The first line rings the bell, turns on flashing characters, and 
displays (using double size characters) the top half of your message. 
The second line rings the bell again, and displays the bottom half of 
your message. The third line writes the current time and then turns 
off the flash characteristic to return your terminal to normal. 

If you do not have a DEC—CRT terminal, then the procedure rings 
your terminal bell, and displays your message and the time. 

• The DELETE command causes the procedure WAKEUP.COM to 
delete itself after it executes. 

© After creating WAKEUP.COM, the procedure spawns a subprocess and 
directs the subprocess to use WAKEUP.COM as the input command file. 
The /NOWAIT qualifier allows you to continue working at your terminal 
while the subprocess executes commands from WAKEUP.COM. At the 
specified time, WAKEUP.COM displays your message on your terminal. 

Note that, by default, the SPAWN command passes global and local 
symbols to a subprocess. Therefore, although you provide values for 
the symbols WAIT-TIME and MESSAGE-TEXT in REMINDER.COM, 
WAKEUP.COM can also access these symbols. 

© The procedure restores the original verification settings before it exits. 

Sample Execution 

$ ^REMINDER 

Enter time to send reminder (hh:mm): 12:00 
Enter message: TIME FOR LUNCH 
7.DCL-S-SPAWNED, process BLUTO.l spawned 
$ 


TIME FOR LUNCH 
15-APR-1984 12:00:56.99 
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The procedure prompts for a time value and for your message. Then the 
procedure spawns a subprocess that displays your message. You can continue 
working at your terminal; at the specified time, the subprocess rings the 
terminal bell, displays your message, and displays the time. 


A.3 DIR.COM 

$ ! 

$ ! Command procedure implementation of DIRECTORY/SIZE=ALL/DATE 
$ ! command 
$ ! 

$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE") 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 

$ ! 

$ ! Replace any blank field of the PI file specification with 
$ ! a wildcard character 
$ ! 

$ PI = F$PARSE(P1,"*.*;*") O 

$ ! 

$ ! Define initial values for symbols 

$ ! 

$ FIRST.TIME = "TRUE" 

$ FILE.COUNT = 0 
$ TOTAL.ALLOC = 0 
$ TOTALISED = 0 
$ 

$ LOOP: © 

$ FILESPEC = F$SEARCH(P1) 

$ ! Find next file in directory 
$ IF FILESPEC .EQS. "" THEN GOTO DONE 

$ ! If no more files, then done 
$ IF .NOT. FIRST.TIME THEN GOTO SHOW.FILE 

$ ! Print header only once 
$ ! 

$ ! Construct and output the header line 
$ ! 

$ FIRST.TIME = "FALSE" © 

$ DIRSPEC = F$PARSE(FILESPEC,,, "DEVICE") - 

+F$PARSE(FILESPEC,,, "DIRECTORY") 

$ WRITE SYSSOUTPUT "" 

$ WRITE SYS$OUTPUT "Directory ".DIRSPEC 

$ WRITE SYSSOUTPUT "" 

$ LASTDIR = DIRSPEC 

$ 

$ ! 

$ ! Put the file name together, get some of the file attributes, and 
$ ! type the information out 
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$ • 

$SH0W_FILE: 

$ FILE.COUNT = FILE.COUNT + 1 

$ FILENAME = F$PARSE(FILESPEC.,. "NAME") - O 

+ F$PARSE(FILESPEC,,, "TYPE") - 
+ F$PARSE(FILESPEC,,. "VERSION") 

$ ALLOC = F$FILE_ATTRIBUTES(FILESPEC, "ALQ") 

$ USED = F$FILE_ATTRIBUTES(FILESPEC, "EOF") 

$ TOTAL.ALLOC = TOTAL.ALLOC + ALLOC 
$ TOTALJJSED = TOTALISED + USED 

$ REVISED = F$FILE_ATTRIBUTES(FILESPEC."RDT") 

$ LINE = F$FA0("!19AS !5UL/!5<!UL!> !17AS".FILENAME,- 

USED. ALLOC, REVISED) 

$ WRITE SYSSOUTPUT LINE 

$ GOTO LOOP 

$ 

$ ! 

$ ! Output summary information, reset verification, and exit 

$ ! 

$ DONE: 0 

$ WRITE SYS$OUTPUT "" 

$ WRITE SYSSOUTPUT "Total of ”FILE_COUNT’ files, " + - 

" * ’ TOTALISED 7 ’ ' TOTAL.ALLOC ’ blocks. " 

$ SAVE_VERIFY_PROCEDURE = FSVERIFY(SAVE_VERIFY_PROCEDURE.SAVE_VERIFY_IMAGE) 

$ EXIT 


Notes 

O This procedure uses the F$PARSE function to place asterisks in blank 
fields in PI, the user-supplied file specification. If you do not specify 
a parameter when you execute DIR.COM, then the FSPARSE function 
assigns the value "*.*;*" to PI. This causes DIR.COM to display all files 
in the current default directory. 

© The F$SEARCH lexical function searches the directory for the file (or 
files) indicated by PI. If PI contains any wildcards (asterisks), the 
F$SEARCH function returns all matching file specifications. After the last 
file specification has been returned, the procedure branches to the label 
DONE. 

0 The first time through the loop, the procedure writes a header for the 
directory display. This header includes the device and directory names. 
To obtain these names, the procedure uses the FSPARSE function. 

0 The procedure uses the FSPARSE lexical function to extract the file name 
from each file specification in the directory. The FSFILE —ATTRIBUTES 
lexical function then obtains blocks used, blocks allocated, and creation 
date information about each file. Finally, the F$FAO function formats a 
single display line for each file in the directory. The F$FAO function uses 
the file name and file attribute information as arguments. 

0 When FSSEARCH returns a null string, the procedure branches to the 
label DONE and displays summary information showing the total number 
of files, the total number of blocks used, and the total number of blocks 
allocated in the directory. 
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Sample Execution 

$ QDIR [VERN]*.COM 


Directory DISK4:[VERN] 


BATCH.COM;1 

1/3 

16-JUN-1984 11:43 

CALC.COM;3 

1/3 

16-JUN-1984 11:30 

CONVERT.COM;! 

5/6 

16-JUN-1984 15:23 


LOGIN.COM;34 

2/3 

16-JUN-1984 13:17 

PID.COM;7 

1/3 

16-JUN-1984 09:49 

SCRATCH.COM;6 

1/3 

16-JUN-1984 11:29: 


Total of 15 files, 22/48 blocks. 


The procedure returns information on all COM files in the directory [VERN]. 


A.4 SYS.COM 

$ ! 

$ ! Displays information about owner, group, or system processes. 

$ • 

$ ! Turn off verification and save current settings 
$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE") 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 

$ CONTEXT = "" ! Initialize PID search context O 

$ ! 

$ ! Output header line. 

$ ! 

$ WRITE SYS$OUTPUT " PID Username Term Process " + - © 

"name State Pri Image" 

$ ! 

$ ! Output process information. 

$ ! 

SLOOP: 

$ ! 

$ ! Get next PID. If null, then done. 

$ ! 

$ PID = FSPID(CONTEXT) © 

$ IF PID .EQS. "" THEN GOTO DONE 

$ ! 

$ ! Get image file specification and extract the file name. 

$ ! 

$ IMAGNAME = FSGETJPI(PID,"IMAGNAME") © 

$ IMAGNAME = F$PARSE(IMAGNAME,,,"NAME","SYNTAX.ONLY") 

$ ! 

$ ! Get terminal name. If none, then describe type of process. 

$ ! 

$ TERMINAL = FSGETJPI(PID,"TERMINAL") © 

$ IF TERMINAL .EQS. "" THEN - 

TERMINAL = "-"+FSEXTRACT(0,3,FSGETJPI(PID,"MODE"))+"-" 
S IF TERMINAL .EQS. "-INT-" THEN TERMINAL = "-DET-" 

$ IF FSGETJPI(PID."OWNER") .NE. 0 THEN TERMINAL = "-SUB-" 
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$ ! 

$ ! Get some more information, put process line together, 

$ ! and output it. 

$ ! 

$ LINE = F$FAO("!AS !12AS !7AS !15AS !5AS !2UL/!UL I10AS", - 0 

PID.F$GETJPI(PID."USERNAME").TERMINAL.- 
F$GETJPI(PID."PRCNAM").- 
F$GETJPI(PID."STATE"),F$GETJPI(PID,"PRI") 

F$GETJPI(PID."PRIB").IMAGNAME) 

$ WRITE SYSSOUTPUT LINE 

$ GOTO LOOP 

$ ! 

$ ! Restore verification and exit. 

$ ! 

$DONE: 

$ SAVE.VERIFY.PROCEDURE = F$VERIFY(SAVE_VERIFY_PROCEDURE,SAVE_VERIFY_IMAGE) 
$ EXIT 


Notes 

O The symbol CONTEXT is initialized with a null value. This symbol will 
be used with the F$PID function to obtain a list of process identification 
numbers. 

© The procedure writes a header for the display. 

© The procedure gets the first process identification (PID) number. If 
the current process lacks GROUP or WORLD privilege, the PID of the 
current process is returned. If the current process has GROUP privilege, 
the first PID in the group list is returned. The first PID in the system 
list is returned if the current process has WORLD privilege. The function 
continues to return the next PID in sequence until the last PID is returned. 
At this point, a null string is returned, and the procedure branches to the 
end. 

© The procedure uses the F$GETJPI lexical function to get the image file 
specification for each PID. The F$PARSE function extracts the file name 
from the specification returned by the F$GETJPI function. 

© The procedure uses the F$GETJPI function to get the terminal name for 
each PID. The F$EXTRACT function extracts the first three characters of 
the MODE specification returned by F$GETJPI(PID,"MODE") to determine 
the type of process. The F$GETJPI function is used again to determine 
whether the process is a subprocess. 

© The procedure uses the F$GETJPI lexical function to get the user name, 
process name, process state, process priority, and process base priority for 
each PID returned. The F$FAO lexical function formats this information 
into a screen display. 
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Sample Execution 

$ QSYS 


PID 

Username 

Term 

Process name 

State 

Pri Image 

00050011 

NETNONPRIV 

-NET- 

MAIL_14411 

LEF 

9/4 MAIL 

00040013 

STOVE 

RTA6: 

STOVE 

LEF 

9/4 

00140015 

MAROT 

-DET- 

DMFBOACP 

HIB 

9/8 F11BAC 

00080016 

THOMPSON 

-DET- 

MTAOACP 

HIB 

12/8 MTAAACP 

00070017 

JUHLES 

TTF1: 

JUHLES 

LEF 

9/4 


00040018 

MARCO 

TTA2: 

MARCO 

HIB 

9/4 RTPAD 

0018001A 

VERN 

RTA3: 

VERN 

LEF 

9/4 

0033001B 

YISHA 

RTA7: 

YISHA 

CUR 

4/4 

0002004A 

SYSTEM 

-DET- 

ERRFMT 

HIB 

12/7 ERRFMT 


This procedure returns information on all processes on the system. The 
current process has WORLD privilege. 


A.5 GETPARMS.COM 

$ ! Procedure to count the number of parameters passed to a command 
$ ! procedure. This number is returned as the global symbol PARMCOUNT. 

$ ! 

$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE") O 
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 

$ ! 

$ IF PI .EqS. "?" THEN GOTO TELL © 

$ ! 

$ ! Loop to count the number of parameters passed. Null parameters are 
$ ! counted until the last non-null parameter is passed. 

$ ! 

$ COUNT =0 © 

$ LASTNONNULL = 0 

$ LOOP: 

$ IF COUNT ,EQ. 8 THEN GOTO END_COUNT 

$ COUNT = COUNT + 1 

$ IF P’COUNT’ .NES. "" THEN LASTNONNULL = COUNT 

$ GOTO LOOP 
$ ! 

$ END.COUNT: © 

$ ! 

$ ! Place the number of non-null parameters passed into PARMCOUNT. 

$ ! 

$ PARMCOUNT == LASTNONNULL 
$ ! 

$ ! Restore verification setting, if it was on, before exiting 
$ ! 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY(SAVE_VERIFY_PROCEDURE,SAVE_VERIFY_IMAGE) © 
$ EXIT 
$ • 

$ TELL: © 

$ TYPE SYS$INPUT 

This procedure counts the number of parameters passed to 
another procedure. This procedure can be called by entering 
the string: 
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QGETPARMS ’PI *P2 ’P3 ’P4 ’P5 ’P6 ’P7 ’P8 
in any procedure. On return, the global symbol PARMCOUNT 
contains the number of parameters passed to the procedure. 

$ • 

$ EXIT 

Notes 

O The procedure saves the current image and procedure verification settings 
before setting verification off. 

© If a question mark character was passed to the procedure as a parameter, 
the procedure branches to the label TELL (Note 6). 

© A loop is established to count the number of parameters that were 
passed to the procedure. The counters COUNT and LASTNONNULL 
are initialized to 0 before entering the loop. Within the loop, COUNT is 
incremented and tested against the value 8. If COUNT is equal to 8, the 
maximum number of parameters has been entered. Each time a non-null 
parameter is passed, LASTNONNULL is equated to that parameter's 
number. 

Each time the IF command executes, the symbol COUNT has a different 
value. The first time, the value of COUNT is 1 and the IF command 
checks PI. The second time, it checks P2, and so on. 

© When the parameter count reaches 8, the procedure branches to END- 
COUNT. The symbol LASTNONNULL contains the count of the last 
non-null parameter passed. This value is placed in the global symbol 
PARMCOUNT. PARMCOUNT must be defined as a global symbol so 
that its value can be tested at the calling command level. 

© The original verification settings are restored. 

© At the label TELL, the TYPE command displays data that is included 
in the input stream. (In command procedures, the input stream is the 
command procedure file.) The TYPE command displays instructions on 
how to use GETPARMS.COM. 

Sample Execution 

The procedure SORTFILES.COM requires the user to pass three non-null 

parameters. The SORTFILES.COM procedure can contain the following lines: 

$ QGETPARMS ’PI’ ’P2’ ’P3’ ’P4’ ’P5’ ’P6’ ’P7’ ’P8’ 

$ IF PARMCOUNT .NE. 3 THEN GOTO NOT.ENOUGH 


$NOT_ENOUGH: 

$ WRITE SYS$OUTPUT - 

"Three non-null parameters required. Type SORTFILES HELP for info." 
$ EXIT 

The procedure SORTFILES.COM can be invoked as follows: 

$ QSORTFILES DEF 4 

Three non-null parameters required. Type SORTFILE HELP for info. 
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In the previous example, the procedure SORTFILES.COM defines the symbol 
GETPARMS as a synonym for @GETPARMS and its parameters. For this 
procedure to be properly invoked, that is, for the parameters that are passed 
to SORTFILES to be passed to GETPARMS intact for processing, the synonym 
must be preceded with an apostrophe. 

If the return value from GETPARMS is not 3, SORTFILES outputs an error 
message and exits. 


A.6 


EDITALL.COM 

$ ! Procedure to edit all files in a directory with a 
$ ! specified file type. Use PI to indicate the file type. 

$ ! _ 

$ ON CONTROL_Y THEN GOTO DONE ! CTRL/Y action V 

$ ON ERROR THEN GOTO DONE 
$ ! 

$ ! Check for file type parameter. If one was entered, continue; 

$ ! otherwise, prompt for a parameter. 

$ ! 

$ IF PI .NES. "" THEN GOTO OKAY © 

$ INQUIRE PI "Enter file type of files to edit" 

$ 1 

$ ! List all files with the specified file type and write the DIRECTORY 
$ ! output to a file named DIRECT.OUT 
$ ! 

OKAY: 


DIRECT0RY/VERSI0NS=1/C0LUMNS=1 - © 

/NODATE/NOSIZE - 
/NOHEADING/NOTRAILING - 
/OUTPUT=DIRECT.OUT *.'PI’ 

IF .NOT. $STATUS THEN GOTO ERROR_SEC 


$ • 

$ OPEN/READ/ERROR=ERROR_SEC DIRFILE DIRECT.OUT 
$ ! 

$ ! Loop to read directory file 
$ ! 

* nfwt tnf• © 

$ READ/END=DONE DIRFILE NAME 

$ DEFINE/USER.MODE SYS$INPUT SYS$COMMAND: 

$ EDIT ’NAME’ 

$ GOTO NEWLINE 


$ ! 

$ DONE: 


o 


CLOSE DIRFILE/ERROR=NOTOPEN 
NOTOPEN: 

DELETE DIRECT.OUT;* 

EXIT 

! 

ERROR.SEC: 

WRITE SYS$OUTPUT "Error: ",F$MESSAGE($STATUS) 
DELETE DIRECT.OUT;* 

EXIT 


Redefine SYS$INPUT 
Edit the file 


! Close the file 


! Delete temp file 
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Notes 

O ON commands establish condition handling for this procedure. If 

CTRL/Y is pressed at any time during the execution of this procedure, the 
procedure branches to the label DONE. Similarly, if any error or severe 
error occurs, the procedure branches to the label DONE. 

© The procedure checks whether a parameter was entered. If not, the 
procedure prompts for a file type. 

© The DIRECTORY command lists all files with the file type specified 
as PI. The command output is written to the file DIRECT.OUT. The 
/VERSI0NS=1 qualifier requests that only the highest numbered version 
of each file be listed. The /NOHEADING and /NOTRAILING qualifiers 
request that no heading lines or directory summaries be included in the 
output. The /COLUMNS=l qualifier ensures that one file name per 
record is given. 

© The IF command checks the return value from the DIRECTORY command 
by testing the value of $STATUS. If the DIRECTORY command does not 
complete successfully, then $STATUS has an even integer value, and the 
procedure branches to the label ERROR_SEC. 

© The OPEN command opens the directory output file and gives it a logical 
name of DIRFILE. 

© The READ command reads a line from the DIRECTORY command output 
into the symbol name NAME. After it reads each line, the procedure uses 
the DEFINE command to redefine the input stream for the edit session 
(SYS$INPUT) to be the terminal. Then, it invokes the editor, specifying 
the symbol NAME as the file specification. When the edit session is 
completed, the command interpreter reads the next line in the command 
procedure and branches to the label NEWLINE. When the procedure has 
edited all files of the specified file type in the directory, it branches to the 
label DONE. 

© The label DONE is the target label for the /END qualifier on the READ 
command and the target label for the ON CONTROL _Y and ON ERROR 
conditions set at the beginning of the procedure. At this label, the 
procedure performs the necessary cleanup operations. 

The CLOSE command closes the DIRECTORY command output file; the 
/ERROR qualifier specifies the label on the next line in the file. This use 
of /ERROR suppresses any error message that would be displayed if the 
directory file is not open. For example, this would occur if CTRL/Y were 
pressed before the directory file were opened. 

The second step in cleanup is to delete the temporary directory file. 

Sample Execution 

$ QEDITALL DAT 


•/.DELETE-1-FILDEL, device: [directory]DIRECT.OUT; 1 deleted (x blocks) 

The procedure EDITALL is invoked with PI specified as DAT. The procedure 
creates a directory listing of all files in the default directory whose file types 
are DAT and invokes the editor to edit each one. After you finish editing 
the last file with the file type dat, the procedure deletes the temporary file 
DIRECT.OUT and displays an informational message at your terminal. 
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A.7 FORTUSER.COM 

$ ! Procedure to create, compile, link, execute, and debug 
$ ! FORTRAN programs. Users can enter only the commands listed 
$ ! in the symbol OPTION.TABLE. 

$ SET NOCONTROL=Y O 

$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE") 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 

$ OPTION.TABLE = "EDIT/COMPILE/LINK/RUN/EXECUTE/DEBUG/PRINT/HELP/FILE/DONE/" © 

$ TYPE SYS$INPUT © 

VMS FORTRAN Command Interpreter 

Enter name of file with which you would like to work. 

$ ! 

$ ! Set up for initial prompt 
$ ! 

$ PROMPT = "INIT" © 

$ GOTO HELP ! Print the initial help message 

$ ! 

$ ! after the first prompting message, use the prompt: Command 

! U: 

$ PROMPT = "GET.COMMAND" 

$ GOTO FILE ! Get initial file name 

$ ! 

$ ! Main command parsing routine. The routine compares the current 
$ ! command against the options in the option table. When it finds 
$ ! a match, it branches to the appropriate label. 

$ ! 

$ GET.COMMAND: 

$ ON CONTROL.Y THEN GOTO GET.COMMAND ! CTRL/Y resets prompt © 

$ SET CONTROL=Y 

$ ON WARNING THEN GOTO GET.COMMAND ! If any, reset prompt 

$ INQUIRE COMMAND "Command" 

$ IF COMMAND .EQS. "" THEN GOTO GET.COMMAND 

$ IF F$LOCATE(COMMAND + "/", OPTION.TABLE) .EQ. F$LENGTH(OPTION.TABLE) - © 

THEN GOTO INVALID.COMMAND 

$ GOTO ’COMMAND’ 

$ ! 

$ INVALID.COMMAND: O 

$ WRITE SYSSOUTPUT " Invalid command" 

$ ! 

$ HELP: © 

$ TYPE SYS$INPUT 

The commands you can enter are: 

FILE Name of FORTRAN program in your current 

default directory. Subsequent commands 
process this file. 

EDIT Edit the program. 

COMPILE Compile the program with VAX FORTRAN. 

LINK Link the program to produce an executable image. 

RUN Run the program’s executable image. 

EXECUTE Same function as COMPILE, LINK, and RUN. 

DEBUG Run the program under control of the debugger. 

PRINT Queue the most recent listing file for printing. 

DONE Return to interactive command level. 

HELP Print this help message. 

Enter CTRL/Y to restart this session 
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$ GOTO ’PROMPT’ 0 
$ EDIT: ® 

$ DEFINE/USER.MODE SYS$INPUT SYS$COMMAND: 

$ EDIT ’FILE.NAME’.FOR 

$ GOTO GET.COMMAND 

$ COMPILE: 

$ FORTRAN ’FILE.NAME’/LIST/OBJECT/DEBUG 

$ GOTO GET.COMMAND 

$ LINK: 

$ LINK ’FILE.NAME’/DEBUG 

$ PURGE ’FILE.NAME’.*/KEEP=2 

$ GOTO GET.COMMAND 

$ RUN: 

$ DEFINE/USER.MODE SYS$INPUT SYSSCOMMAND: 

$ RUN/NODEBUG ’FILE.NAME’ 

$ GOTO GET.COMMAND 

$ DEBUG: 

$ DEFINE/USER.MODE SYS$INPUT SYS$COMMAND: 

$ RUN ’FILE.NAME’ 

$ GOTO GET.COMMAND 

$ EXECUTE: 

$ FORTRAN ’FILE.NAME’/LIST/OBJECT 

$ LINK/DEBUG ’FILE.NAME’ 

$ PURGE ’FILE.NAME’.*/KEEP=2 

$ RUN/NODEBUG ’FILE.NAME’ 

$ GOTO GET.COMMAND 

$ PRINT: 

$ PRINT ’FILE.NAME’ 

$ GOTO GET.COMMAND 

$ BADFILE: © 

$ WRITE SYS$OUTPUT "File must be in current default directory." 

$ FILE: 

$ INQUIRE FILE.NAME "File name" 

$ IF FILE.NAME .EQS. "" THEN GOTO FILE 

$ IF F$PARSE(FILE_NAME,.."DIRECTORY") .NES. F$DIRECTORY() - © 

THEN GOTO BADFILE 

$ FILE.NAME = F$PARSE(FILE.NAME.,,"NAME") 

$ GOTO GET.COMMAND 

$ DONE: 

$ EXIT 


Notes 

O The SET NOCONTROL=Y command ensures that the user who logs in 
under the control of this procedure cannot interrupt the procedure or any 
command or program in it. 

© The option table lists the commands that the user will be allowed to 
execute. Each command is separated by a slash. 

© The procedure introduces itself. 

© The symbol name PROMPT is given the value of a label in the procedure. 
When the procedure is initially invoked, this symbol has the value 
INIT. The HELP command text terminates with a GOTO command that 
specifies the label PROMPT. When this text is displayed for the first time, 
the GOTO command results in a branch to the label HELP. This displays 
the HELP message that explains the commands that you can enter. 

Then, the procedure branches back to the label INIT, where the value 
for PROMPT is changed to "GET_COMMAND." Finally, the procedure 
branches to the label FILE to get a file name. Thereafter, when the help 
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text is displayed, the procedure branches to the label GET—COMMAND 
to get the next command. 

© The CTRL/Y condition action is set to return to the label GET- 

COMMAND, as is the warning condition action. The procedure prompts 
for a command and continues to prompt, even if nothing is entered. To 
terminate the session and return to interactive command level, enter the 
command DONE. 

© The procedure uses the F$LOCATE and F$LENGTH lexical functions 
to determine whether command is included in the list of options. The 
F$LOCATE function searches for the user-entered command, followed by 
a slash. (For example, if you enter EDIT, the procedure searches for EDIT 
/.) If the command is not included in the option list, then the procedure 
branches to the label INVALID-COMMAND. If the command is valid, 
the procedure branches to the appropriate label. 

O At the label INVALID—COMMAND, the procedure writes an error 

message and displays the help text that lists the commands that are valid. 

© The help text lists the commands that are valid. This text is displayed 
initially. It is also displayed whenever the user enters the HELP 
command or any invalid command. 

© At the conclusion of the HELP text, the GOTO command specifies the 
symbol name PROMPT. When this procedure is first invoked, the symbol 
has the value INIT. Thereafter, it has the value GET—COMMAND. 

© Each valid command in the list has a corresponding entry in the option 
table and a corresponding label in the command procedure. For the 
commands that read input from the terminal, for example, EDIT, the 
procedure contains a DEFINE command that defines the input stream as 
SYS$COMMAND. 

© At the label BADFILE, the procedure displays a message indicating that 
the file must be in the current directory. Then the procedure prompts for 
another file name. 

© After obtaining a file name, the procedure checks that you have not 
specified a directory that is different from your current default directory. 
The procedure then uses the F$PARSE function to extract the file name. 
(Each command supplies the appropriate default file type.) Next, 
the procedure branches back to the label GET—COMMAND to get a 
command to process the file. 

Sample Execution 

This example illustrates how to use this command procedure as a captive 

command procedure. 

Username: CLASS30 

Password: 

VMS Version 5.0 

VMS FORTRAN Command Interpreter 

Enter name of file with which you would like to work. 

The commands you can enter are: 
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FILE Name of FORTRAN program in your current 

default directory. Subsequent commands 
process this file. 

EDIT Edit the program. 

COMPILE Compile the program with VAX FORTRAN. 

LINK Link the program to produce an executable image. 

RUN Run the program’s executable image. 

EXECUTE Same function as COMPILE, LINK and RUN. 

DEBUG Run the program under control of the debugger. 

PRINT Queue the most recent listing file for printing. 

DONE Return to interactive command level. 

HELP Print this help message. 


Enter CTRL/Y to restart this session 
File name: AVERAGE 
Command: COMPILE 
Command: LINK 
Command: RUN 
Command: FILE 
File name: READFILE 
Command: EDIT 


This sample execution illustrates a session in which a user named CLASS30 
logs in to the account controlled by the FORTUSER command procedure. The 
FORTUSER command procedure displays the commands the user is allowed 
to execute, as well as an instruction for restarting the session. Next, the user 
specifies the file AVERAGE, compiles, links, and runs it. Then, the user enters 
the FILE command to begin working on another file. 


A.8 LISTER.COM 

$ ! Procedure to accumulate programmer names and document 
$ ! file names. After all names and files are entered, they are 
$ ! sorted in alphabetic order by programmer name and printed on 
$ ! the system printer. 

$ ! 

$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE") O 
$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 

$ ! 

$ OPEN/WRITE OUTFILE DATA.TMP ! Create output file © 

$ ! 

$ ! Loop to obtain programmers’ last names and file names, 

$ ! and write this data to DATA.TMP. 

$ ! 

$ LOOP: © 

$ INQUIRE NAME "Programmer (press RET to quit)" 

$ IF NAME .EQS. "" THEN GOTO FINISHED 

$ INQUIRE FILE "Document file name" 

$ RECORD[0,20]:=’NAME’ © 

$ RECORD[21,20]:=’FILE’ 

$ WRITE OUTFILE RECORD 

$ GOTO LOOP 

$ FINISHED: 

$ CLOSE OUTFILE 
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$ ! 

$ DEFINE/USER_MODE SYS$OUTPUT: NL: ! Suppress sort output 

$ SORT/KEY=(POSITION:1,SIZE=20) DATA.TMP DOC.SRT © 

$ ! 

$ OPEN/WRITE OUTFILE DOCUMENT.DAT © 

$ WRITE OUTFILE "Programmer Files as of ",F$TIME() 

$ WRITE OUTFILE "" 

$ RECORD[0,20]:="Programmer Name" 

$ RECORD[21.20]:="File Name" 

$ WRITE OUTFILE RECORD 
$ WRITE OUTFILE "" 

$ ! 

$ CLOSE OUTFILE O 
$ APPEND DOC.SRT DOCUMENT.DAT 
$ PRINT DOCUMENT.DAT 
$ ! 

$ INQUIRE/CLEAN_UP "Delete temporary files [Y.N]" © 

$ IF CLEAN.UP THEN DELETE DATA.TMP;*.DOC.SRT;* 

$ SAVE_VERIFY_PROCEDURE = FSVERIFY(SAVE_VERIFY_PROCEDURE.SAVE_VERIFY_IMAGE) 
$ EXIT 


Notes 

© LISTER.COM saves the current verification setting and sets verification 
off. 

© The OPEN command opens a temporary file for writing. 

© INQUIRE commands prompt for a programmer name and for a file 
name. If a null line, signaled by RETURN, is entered in response to the 
INQUIRE command prompt, the procedure assumes that no more data is 
to be entered and branches to the label FINISHED. 

© After assigning values to the symbols NAME and FILE, the procedure 
uses the character string overlay format of an assignment statement 
to construct a value for the symbol RECORD. In columns 1 through 
21 of RECORD, the current value of NAME is written. The command 
interpreter pads the value of NAME with spaces to fill the 20-character 
length specified. 

Similarly, the next 20 columns of RECORD are filled with the value of 
FILE. Then, the value of RECORD is written to the output file. 

© After the file has been closed, the procedure sorts the output file 

DATA.TMP. The DEFINE command directs the SORT command output 
to the null file NL. Otherwise, these statistics would be displayed on the 
terminal. 

The sort is performed on the first 20 columns, that is, by programmer 
name. 

The sorted output file has the name DOC.SRT. 

© The procedure creates the final output file, DOCUMENT.DAT, with the 
OPEN command. The first lines written to the file are header lines, giving 
a title, the date and time of day, and headings for the columns. 

© The procedure closes the file DOCUMENT.DAT and appends the sorted 
output file, DOC.SRT, to it. Then, the output file is queued to the system 
printer. 
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© Last, the procedure prompts to determine whether to delete the 
intermediate files. If a true response (T, t, Y, or y) is entered to the 
INQUIRE command prompt, the files DATA.TMP and DOC.SRT are 
deleted. Otherwise, they are retained. 

Sample Execution 

$ GLISTER 

Programmer: WATERS 

Document file name: CRYSTAL.CAV 

Programmer: JENKINS 

Document file name: MARIGOLD.DAT 

Programmer: MASON 

Document file name: SYSTEM.SRC 

Programmer: ANDERSON 

Document fil e na me: JUNK.J 

Programmer: IretI 

Delete temporary files [Y,N]:y 

The output file resulting from this execution of the procedure is as follows: 

Programmer Files as of 31-DEC-1989 16:18:58.79 

Programmer Name File Name 

ANDERSON JUNK.J 

JENKINS MARIGOLD.DAT 

MASON SYSTEM.SRC 

WATERS CRYSTAL.CAV 


A.9 CALC.COM 

$ ! Procedure to calculate expressions. If you enter an 
$ ! assignment statement, then CALC.COM evaluates the expression 
$ ! and assigns the result to the symbol you specify. In the next 
$ ! iteration, you can use either your symbol or the symbol Q to 
$ ! represent the current result. 

$ ! 

$ ! If you enter an expression, then CALC.COM evaluates the 
$ ! expression and assigns the result to the symbol Q. In 
$ ! the next iteration, you can use the symbol Q to represent 
$ ! the current result. 

$ ! 

$ SAVE_VERIFY_IMAGE = F$ENVIRONMENT("VERIFY_IMAGE") 

$ SAVE_VERIFY_PROCEDURE = F$VERIFY(0) 

$ START: 

$ ON WARNING THEN GOTO START O 

$ INQUIRE STRING "Calc" © 

$ IF STRING .EQS. "" THEN GOTO CLEAN.UP 

$ IF F$LOCATE("=",STRING) .EQ. F$LENGTH(STRING) THEN GOTO EXPRESSION 

$ ! 

$ ! Execute if string is in the form symbol = expression 
$ STATEMENT: © 

$ ’STRING’ ! Execute assignment statements 

$ SYMBOL = F$EXTRACT(0.F$LOCATE("=".STRING)-1,STRING) ! get symbol name 
$ Q = ’SYMBOL’ ! Set up q for future iterations 

$ LINE = F$FAO("Decimal = !SL Hex = !-!XL Octal = !-!OL".Q) 

$ WRITE SYS$OUTPUT LINE 

$ GOTO START 

$ ! 
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$ ! 

$ ! Execute if string is an expression 
$ EXPRESSION: O 

$ Q = F$INTEGER(* STRING’) ! Can use Q in next iteration 

$ LINE = F$FAO("Decimal = !SL Hex = !-!XL Octal = !-!OL",Q) 

$ WRITE SYS$OUTPUT LINE 

$ GOTO START 

$ ! 

$ CLEAN.UP: 

$ SAVE_VERIFY.PROCEDURE = F$VERIFY(SAVE_VERIFY_PROCEDURE,SAVE_VERIFY_IMAGE) 
$ EXIT 


Notes 

O The procedure establishes an error handling condition that restarts 
the procedure. If a warning or an error of greater severity occurs, the 
procedure will branch to the beginning where it resets the ON condition. 

This technique ensures that the procedure will not exit if the user enters 
an expression incorrectly. 

© The INQUIRE command prompts for an arithmetic expression. The 
procedure accepts expressions in either of the following formats: 

name = expression 
expression 

If you press RETURN, the procedure assumes the end of a CALC session 
and exits. 

If you enter input in the format "name = expression" then the procedure 
continues executing at the label STATEMENT. Otherwise, the procedure 
branches to the label EXPRESSION. 

© The procedure executes the assignment statement and assigns the result 
of the expression to the symbol. Then the procedure extracts the symbol 
name, and assigns the value of the symbol to Q. This allows you to use 
either Q or your symbol during the next iteration of the procedure. Next, 
the procedure displays the result and then branches back to the label 
START. 

© The procedure evaluates the expression and assigns the result to the 
symbol Q. This allows you to use Q during the next iteration of the 
procedure. Next, the procedure displays the result and then branches 
back to the label START. 


Sample Execution 


$ OCALC 
Calc: 2 * 30 
Decimal = 60 
Calc: Q + 3 
Decimal = 63 
Calc: TOTAL = Q 
Decimal = 67 
Calc: 5 + 7 
Decim al = 12 

Calc: [H3 

$ 


Hex = 0000003C Octal = 00000000074 
Hex = 0000003F Octal = 00000000077 


+ 4 


Hex = 00000043 Octal = 00000000103 
Hex = 0000000C Octal = 00000000014 
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After each prompt from the procedure, the user enters an arithmetic 
expression. The procedure displays the results in decimal, hexadecimal, 
and octal. A null line, signaled by pressing RETURN on a line with no data, 
concludes the CALC session. 


A.10 BATCH.COM 

$ VERIFY.IMAGE = F$ENVIRONMENT("VERIFY.IMAGE") 

$ VERIFY.PROCEDURE = F$VERIFY(0) 

$! 

$! Turn off verification and save current settings. 

$! (This comment must appear after you turn verification 
$! off; otherwise it will appear in the batch job log file.) 

$! 

$! 

$! If this is being executed as a batch job, 

$! (from the SUBMIT section below) go to the EXECUTE_BATCH_JOB section 
$! Otherwise, get the information you need to prepare to execute the 
$! batch job. 

$! 

$ IF F$MODE() .EQS. "BATCH" THEN GOTO EXECUTE_BATCH_JOB O 
$! 

$! 

$! Prepare to submit a command (or a command procedure) as a batch job. 

$! First, determine a mnemonic process name for the batch job. Use the 
$! following rules: 

$! 

$! 1) If the user is executing a single command, then use the verb name. 

$! Strip off any qualifiers that were included with the command. 

$! 2) If the user is executing a command procedure, then use the file name. 

$! 3) Otherwise, use BATCH. 

$! 

$ JOB.NAME = PI © 

$ IF JOB.NAME .EQS. "" THEN JOB.NAME = "BATCH" 

$ IF F$EXTRACT(0,1,JOB.NAME) .EQS. "<3" THEN JOB.NAME = F$EXTRACT(1,999,JOB_NAME) 
$ JOB.NAME = F$EXTRACT(0,F$LOCATE("/",JOB.NAME),JOB.NAME) 

$ JOB.NAME = F$PARSE(JOB.NAME,,,"NAME","SYNTAX.ONLY") 

$ IF JOB.NAME .EQS. "" THEN JOB.NAME = "BATCH" 

$! 

$! 

$! Get the current default device and directory. 

$! 

$ ORIGDIR = F$ENVIRONMENT("DEFAULT") 

$! 

$! 

$! Concatenate the parameters to form the command string to be executed. 

$! If the user did not enter a command string, the symbol COMMAND will have 
$! a null value. 

$! 

$ COMMAND = PI + " " + P2 + " " + P3 + " " + P4 + " " + - © 

P5 + » " + P6 + " " + P7 + " " + P8 

$! 

$! 

$! If the user is executing a single command and if both the command and the 
$! original directory specification are small enough to be passed as 
$! parameters to the SUBMIT command, then submit the batch job now 
$! 

$ IF (PI .NES. "") .AND. (F$LENGTH(COMMAND) .LE. 255) .AND. - © 

(F$LENGTH(ORIGDIR) .LE. 255) THEN GOTO SUBMIT 

$! 
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$! 

$! If the single command to be executed in the batch job is very large, or 
$! if you have to prompt for commands to execute in the batch job, then 
$! create a temporary command procedure to hold those commands and get the 
$! fully expanded name of the command procedure. 

$! 

$ CREATE_TEMP_FILE: 

$ ON CONTROL.Y THEN GOTO CONTROL.Y.HANDLER 0 

$ OPEN/WRITE/ERROR=FILE_OPEN_ERROR TEMPFILE SYS$SCRATCH:’JOB.NAME’.TMP © 

$ FILESPEC = F$SEARCH("SYSSSCRATCH:" + JOB.NAME + ".TMP") 

$! 

$! By default, have the batch job continue if it encounters any errors. 

$! 

$ WRITE TEMPFILE "$ SET NOON" 

$! 

$! Either write the single large command to the file, or prompt for 
$! multiple commands and write them to the file. 

$! 

$ IF COMMAND .NES. " " THEN GOTO WRITE.LARGE.COMMAND 

$ 

$ LOOP: 

$ READ /END_OF_FILE=CLOSE_FILE /PROMPT="Command: " SYS$COMMAND COMMAND 

$ IF COMMAND .EQS. "" THEN GOTO CLOSE.FILE 

$ WRITE TEMPFILE "$ ".COMMAND 

$ GOTO LOOP 

$ 

$ WRITE.LARGE.COMMAND: 

$ WRITE TEMPFILE "$ ".COMMAND 
$ 

$! 

$! Finish the temporary file by defining a symbol so that you will know 
$! the name of the command procedure to delete and then close the file. 

$! Define the symbol COMMAND to mean "execute the command procedure 
$! you have just created". Then submit the batch job and execute 
$! this command procedure in the batch job. 

$! 

$ CLOSE.FILE: O 

$ WRITE TEMPFILE "$ BATCH$DELETE_FILESPEC == """.FILESPEC,"""" 

$ CLOSE TEMPFILE 

$ ON CONTROL.Y THEN EXIT 

$ COMMAND = "®" + FILESPEC 

$! 

$! 

$! Submit BATCH.COM as a batch job, and pass it two parameters. 

$! PI is the command (or name of the command procedure) to execute. 

$! P2 is the directory from which to execute the command. 

$! 

$ SUBMIT: © 

$ SUBMIT/NOTIFY/NOPRINT ’F$ENVIRONMENT("PROCEDURE")’ /NAME=’JOB.NAME’ - 
/PARAMETERS 3 (" ” COMMAND’"," ” ORIGDIR’") 

$ GOTO EXIT 

$! 

$! 

$! The user pressed CTRL/Y while the temporary command procedure was open. 

$! Close the command procedure, delete it if it exists, and exit. 

$! 
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$ CONTROL.Y.HANDLER: © 

$ CLOSE TEMPFILE 

$ IF F$TYPE(FILESPEC) .NES. "" THEN DELETE/NOLOG ’FILESPEC* 

$ WRITE SYS$OUTPUT "CTRL/Y caused the command procedure to abort." 
$ GOTO EXIT 
$! 

$! 

$! The temporary command procedure could not be created. 

$! Notify the user and exit. 

$ • _ 

$ FILE_OPEN_ERROR: ® 

$ WRITE SYS$OUTPUT "Could not create sys$scratch:".job.name,".tmp" 
$ WRITE SYS$OUTPUT "Please correct the situation and try again." 

$! 

$! 

$! Restore the verification states and exit. 

$! 

$ EXIT* © 

$ VERIFY.PROCEDURE = F$VERIFY(VERIFY_PROCEDURE,VERIFY_IMAGE) 

$ EXIT 
$! 

$! 

$i BATCH.COM was invoked as a batch job. PI contains the command 
$! to execute and P2 the default directory specification. 

$! Return a status code that indicates the termination status of PI. 
$! 

$ EXECUTE_BATCH_JOB: © 

$ SET NOON 

$ VERIFY.PROCEDURE = F$VERIFY(VERIFY_PROCEDURE,VERIFY_IMAGE) 

$ SET DEFAULT ’P2’ 

$ ’PI’ 

$ IF F$TYPE(BATCH$DELETE_FILESPEC) .EQS. "" THEN EXIT $STATUS 

$ STATUS = $STATUS 

$ DELETE /NOLOG ’BATCH$DELETE_FILESPEC’ 

$ EXIT STATUS 


Notes 

O This IF statement tests whether BATCH.COM is executing in batch mode. 
When you invoke BATCH.COM interactively, you provide (as parameters) 
a command string or a command procedure that is to be executed as a 
batch job. If you do not supply any parameters, then BATCH.COM 
prompts you for commands, writes these commands to a file, and then 
executes this command procedure as a batch job. After BATCH.COM 
prepares your command(s) for execution from a batch job, it uses the 
SUBMIT command to submit itself as a batch job and execute your 
command(s) from this job. (See Note 8.) When you invoke BATCH.COM 
as a batch job, the procedure branches to the label EXECUTE—BATCH— 
JOB. Note that you must specify the command or command procedure to 
execute as PI and the default directory as P2 if you execute BATCH.COM 
in batch mode. 

© These commands prepare the batch job for execution. First, the procedure 
constructs a name for the batch job. If a command string was passed, 
then BATCH.COM uses the verb name as the job name. If a command 
procedure was passed, then BATCH.COM uses the file name. If no input 
was passed, then BATCH.COM names the job BATCH. 

© The parameters are concatenated to form the command string to be 
executed. The command string is assigned to the symbol COMMAND. 
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O The SUBMIT command cannot pass a parameter that is greater than 255 
characters. Therefore, the procedure tests that the command string and 
directory name are less than 255 characters long. If both strings are less 
than 255 characters (and if the user did, in fact, pass a command string), 
then the procedure branches to the label SUBMIT. 

© The procedure establishes a CTRL/Y handler, so clean-up operations are 
performed if the user presses CTRL/Y during this section of the command 
procedure. 

© The procedure creates a temporary file to contain the commands to be 
executed. If the user supplies a long command string, the procedure 
branches to WRITE—LARGE—COMMAND and writes this command to 
the temporary file. Otherwise, the procedure prompts for the commands 
to be executed. Each command is written to the temporary file. 

O Before you close the temporary file, write a symbol assignment statement 
to the file. This statement assigns the file name for the temporary file to 
the symbol BATCH$DELETE—FILESPEC. After closing the temporary file, 
the procedure resets the default CTRL/Y handler. Then the procedure 
defines the symbol COMMAND so that, when executed, the symbol 
COMMAND invokes the temporary command file. 

© The procedure submits itself as a batch job, using the defined job name. 
(See Note 2.) The procedure also passes two parameters: the command 
or command procedure to be executed, and the directory from which the 
command should be executed. Then the procedure branches to the label 
EXIT. (See Note 11.) 

© This section performs clean-up operations if the user types CTRL/Y while 
the temporary file is being created. 

© This section writes an error message if the temporary file cannot be 
created. 

© The procedure resets the original verification settings and then exits. 

© These commands are executed when BATCH.COM runs in batch mode. 
First, ON error handling is disabled and the user's default verification 
settings are set. Then the default is set to the directory indicated by P2, 
and the command or command procedure indicated by PI is executed. If 
a temporary file was created, this file is deleted. The completion status for 
PI is saved before deleting BATCH$DELETE—FILESPEC. This completion 
status is returned by the EXIT command. 

Sample Execution 

$ OBATCH RUN MYPROG 

Job RUN (queue SYS$BATCH, entry 1715) started on SYS$BATCH 

This example uses BATCH.COM to run a program from within a batch job. 
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A.11 COMPILE_FILE.COM 

$! This command procedure compiles, links, and runs a file written in Pascal 
$! or FORTRAN. 

$! 

$ ON CONTROL.Y THEN EXIT 
$! 

$ TOP: 

$ INQUIRE FILE "File to process" 

$ IF F$SEARCH(FILE) .NES. "" O 
$ THEN 

$ FILE.TYPE = F$PARSE(FILE,,."TYPE") © ! determine file type 

$ FILE.TYPE = F$EXTRACT(1,F$LENGTH(’FILE_TYPE’),FILE_TYPE) ! remove period 
$! Remove type from file specification 
$ PERIOD.LOC = F$LOCATE(".".FILE) 

$ FILE = F$EXTRACT(0,PERIOD.LOC,FILE) 

$ ON WARNING THEN GOTO OTHER 
$ GOTO ’FILE.TYPE’ 

$ ELSE © 

$ WRITE SYSSOUTPUT FILE, "does not exist" 

$ ENDIF © 

$! 

$ GOTO END 
$! 

$! 

$! 

$ FOR: © 

$ ON ERROR THEN GOTO PRINT 
$ FORTRAN/LIST ’FILE’ 

$ GOTO LINK 

$! 

$ PAS: 

$ ON ERROR THEN GOTO PRINT 

$ PASCAL/LIST ’FILE’ 

$ GOTO LINK 

$! 

$ OTHER: © 

$ WRITE SYSSOUTPUT "Can’t handle files of type .’’FILE.TYPE’" 

$ GOTO END 
$! 

$ LINK: O 

$ ON ERROR THEN GOTO END 

$ WRITE SYSSOUTPUT "Successful compilation ...." 

$ LINK ’FILE’ 

$ DEFINE/USER.MODE SYSSINPUT SYSSCOMMAND 
$ RUN ’FILE’ 

$ GOTO CLEANUP 

$! 

$ PRINT: © 

$ WRITE SYSSOUTPUT "Unsuccessful compilation, printing listing file 

$ PRINT ’FILE’ 

$! 

$ CLEANUP: 

$ DELETE ’FILE’.OBJ; 

$ DELETE ’FILE’.LIS; 

$! 

$ END: 

$ INQUIRE/NOPUNCTUATION ANS "Process another file (Y or N)? " 

$ IF ANS THEN GOTO TOP 

$ EXIT 
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Notes 

O The IF command uses the F$SEARCH lexical function to search the 
directory and determine if the file exists. 

© The command block following the THEN command: 

• uses the F$LENGTH lexical function to determine the length of the 
file type 

• determines the file type 

• removes the period from the file type 

• removes the file type from the file specification to determine the file 
name 

• removes the period from the file name 

• defines an action to perform if an error occurs 

• branches to the label defined by the symbol FILE__TYPE 

© If the file you entered at the "File to process:" prompt does not exist in 
the directory, the command following the ELSE command executes. 

© The ENDIF command ends the IF-THEN-ELSE command language 
construct. 

© The procedure compiles the FORTRAN program and branches to the 
LINK label. If an error occurs during the compilation, the procedure 
branches to the PRINT label. 

© The procedure displays that the program compiled correctly, links and 
runs the program, and branches to the CLEANUP label. The program 
branches to the END label if an error occurs. 

O The procedure enters the listing file of the program in the default print 
queue. 

Sample Execution 

$ @COMPILE_FILE 

File to process: RAND.PAS 

Successful compilation 

V.DELETE-I-FILDEL,WORK: [DESCH]RAND.OBJ; 1 deleted (3 blocks) 
# /,DELETE-I-FILDEL,WORK: [DESCH]RAND.LIS; 1 deleted (9 blocks) 

Process another file (Y or N)? N IretI 
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The following list summarizes each lexical function and its arguments. For 
complete information on each function, including examples, see the VMS DCL 
Dictionary. 

F$CVSI(bit-position .count .integer) 

Extracts bit fields from character string data and converts the result, as a 
signed value, to an integer. 

F$CVTI M E ([input-time][,output-time][,field]) 

Retrieves information about an absolute, combination, or delta time string. 

F$CVU I (bit-position .count .integer) 

Extracts bit fields from character string data and converts the result, as an 
unsigned value, to an integer. 

F$DIRECTORY() 

Returns the current default directory name string. 

F$EDIT(string .edit-list) 

Edits a character string based on the edits specified. 

F$ELEMENT(element-number .delimiter .string) 

Extracts an element from a string in which the elements are separated by a 
specified delimiter. 

F$ENVIRONMENT(item) 

Obtains information about the DCL command environment. 

F$EXTRACT(offset .length .string) 

Extracts a substring from a character string expression. 

F$FAO(control-string [,arg1 ,arg2...arg15]) 

Invokes the $FAO system service to convert the specified control string to a 
formatted ASCII output string. 

F$FILE_ATTRIBUTES(file-spec .item) 

Returns attribute information for a specified file. 

F$GETDVI(device-name .item) 

Invokes the SGETDVI system service to return a specified item of information 
for a specified device. 

F$GETJPI(pid .item) 

Invokes the SGETJPI system service to return accounting, status, and 
identification information for a process. 
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F$GETQUI(function [,item] [,object-id] [,flags]) 

Invokes the $GETQUI system service to return information about queues, 
batch and print jobs currently in those queues, form definitions, and 
characteristic definitions kept in the system job queue file. 

F$GETSYI(item [,node]) 

Invokes the $GETSYI system service to return status and identification 
information about the local system, or about a node in the local cluster, if 
your system is part of a cluster. 

F$IDENTIFIER(identifier,conversion-type) 

Converts an identifier in named format to its integer equivalent, or vice versa. 

F$INTEGER(expression) 

Returns the integer equivalent of the result of the specified expression. 

F$LENGTH(string) 

Returns the length of a specified string. 

F$LOCATE(substring ,string) 

Locates a character or character substring within a string and returns its offset 
within the string. 

F$LOGICAL(logical-name) 

Translates a logical name and returns the equivalence name string. 

F$MESSAGE(status-code) 

Returns the message text associated with a specified system status code value. 

F$MODE() 

Shows the mode in which a process is executing. 

F$PARSE(file-spec [,default-spec] [,related-spec] [,field]) 

Invokes the SPARSE RMS service to parse a file specification and return either 
the expanded file specification or the particular file specification field that you 
request. 

F$PID(context-symbol) 

For each invocation, returns the next process identification number in 
sequence. 

F$PRIVILEGE(priv-states) 

Returns a value of "TRUE" or "FALSE" depending on whether your current 
process privileges match the privileges listed in the argument. 

F$PROCESS() 

Returns the current process name string. 

F$SEARCH(file-spec [,stream-id]) 

Invokes the SSEARCFl RMS service to search a directory file, and returns the 
full file specification for a file you name. 
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F$SETPRV(priv-states) 

Sets the specified privileges and returns a list of keywords indicating the 
previous state of these privileges for the current process. 

F$STRING(expression) 

Returns the string equivalent of the result of the specified expression. 

F$TIME() 

Returns the current date and time of day, in the format dd-mmm-yyyy 
hh:mm:ss.cc. 

F$TRNLNM(logical-name [stable] [,index] [,mode] [,case] [,item]) 

Translates a logical name and returns the equivalence name string or the 
requested attributes of the logical name. 

F$TYPE(symbol-name) 

Determines the data type of a symbol. 

F$USER() 

Returns the current user identification code (UIC). 

F$VERIFY([procedure-value] [,image-value]) 

Returns the integer 1 if command procedure verification is set on; returns the 
integer 0 if command procedure verification is set off. The F$VERIFY function 
also can set new verification states. 
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Commands Frequently Used in Command Procedures 


The following DCL commands are frequently used in command procedures. 
This list also includes commands that you use to control interactive command 
procedures and batch jobs. See the VMS DCL Dictionary for complete 
reference information on each DCL command. 


Name 

Function 

@ 

Executes a command procedure. 

Symbol assignment; equates a local symbol name to 
an integer expression or character string expression. 

Symbol assignment; equates a global symbol name to 
an integer expression or character string expression. 

String assignment; equates a local symbol name to a 
character string. Commonly used to equate a symbol 
to a command string without having to enclose the 
string in quotation marks. 

String assignment; equates a global symbol name to a 
character string. Commonly used to equate a symbol 
to a command string without having to enclose the 
string in quotation marks. 

ASSIGN 

Equates a logical name to a physical device name, 
to a complete file specification, or another logical 
name, and places the equivalence name string in the 
process, group, or system logical name table. 

CALL 

Transfers control to a labeled subroutine in a 
command procedure and creates a new procedure 
level. 

CLOSE 

Closes a file that was opened for input or output with 
the OPEN command and deassigns the logical name 
specified when the file was opened. 

CONTINUE 

Resumes execution of a command procedure or 
image that was interrupted by pressing CTRL/Y or 
CTRL/C. 

DEASSIGN 

Cancels a logical name assignment made with the 
ALLOCATE, ASSIGN, or DEFINE command. 

DECK 

Marks the beginning of an input stream for a 
command procedure when the first nonblank 
character in any data record in the input stream is 
a dollar sign ($). 

DEFINE 

Equates a logical name to a physical device name, 
to a complete file specification, or to another logical 
name, and places the equivalence name string in the 
process, group, or system logical name table. 


C-1 











Commands Frequently Used in Command Procedures 


Name 

Function 

DELETE/ENTRY 

Deletes one or more entries from a print or batch job 
queue. 

DELETE/SYMBOL 

Deletes a symbol definition from a local symbol table 
or from the global symbol table. 

ENDSUBROUTINE 

Terminates a CALL subroutine and returns control to 
the command following the CALL command. 

EOD 

Marks the end of an input stream for a command 
procedure. 

EOJ 

Marks the end of a batch job submitted through a 
system card reader. 

EXIT 

Terminates processing of the current command 
procedure. 

GOSUB 

Transfers control to a labeled subroutine in a 
command procedure but does not create a new 
procedure level. 

GOTO 

Transfers control to a labeled statement in a 
command procedure. 

IF...THEN 

Tests the value of an expression and executes a 
command if the test is true. 

INQUIRE 

Requests interactive assignment of a value for a local 
or global symbol during the execution of a command 
procedure. 

JOB 

Marks the beginning of a batch job submitted through 
a system card reader. 

ON...THEN 

Defines the default courses of action when a 
command or program executed within a command 
procedure (1) encounters an error condition or (2) is 
interrupted by CTRL/Y. 

OPEN 

PASSWORD 

Opens a file for reading or writing. 

Specifies the password associated with the user 
name specified on a JOB card for a batch job 
submitted through a card reader. 

PRINT 

Queues one or more files for printing, either on a 
default system printer or a specified device. 

READ 

Reads a single record from a specified input file and 
assigns the contents of the record to a specified 
symbol name. 

RETURN 

Terminates a GOSUB subroutine procedure and 
returns control to the command following the GOSUB 
command. 

SET CARD-READER 

Defines the default ASCII translation mode for a card 
reader. 

SET CONTROL 

SET ENTRY 

Enables interrupts caused by CTRL/Y and CTRL/T. 

Changes the current status or attributes of a job that 
is not currently executing in a queue. 

SET NOCONTROL 

Disables interrupts caused by CTRL/Y and CTRL/T. 
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Name 

Function 

SET NOON 

Prevents the command interpreter from performing 
error checking following the execution of commands. 

SET NOVERIFY 

Prevents command lines in a command procedure 
from being displayed at a terminal or printed in a 
batch job log file. 

SET ON 

Causes the command interpreter to perform error 
checking following the execution of commands. 

SET OUTPUT-RATE 

Sets the rate at which output is written to a batch job 
log file. 

SET RESTART-VALUE 

Establishes a test value for restarting portions of a 
batch job. 

SET QUEUE/ENTRY 

Changes the current status or attributes of a file that 
is queued for printing or for batch job execution but 
not yet processed. 

SET SYMBOL 

Controls access to local and global symbols in 
command procedures. 

SET VERIFY 

Causes command lines in a command procedure to 
be displayed at a terminal or printed in a batch job log 
file. 

SHOW ENTRY 

Displays the current status of an entry in a print or 
batch job queue. 

SHOW QUEUE 

Displays the current status of entries in the print or 
batch job queues. 

STOP/ABORT 

STOP/ENTRY 

Aborts a job that is currently being printed. 

Deletes an entry from a batch queue while it is 
running. 

STOP/REQUEUE 

Stops the printing of the job currently being printed 
and places that job at the end of the output queue. 

SUBMIT 

Enters one or more command procedures in the batch 
job queue. 

SUBROUTINE 

Begins a CALL subroutine. During the line-by¬ 
line command procedure execution, the command 
language interpreter skips all commands between the 
SUBROUTINE and the ENDSUBROUTINE commands. 

SYNCHRONIZE 

Places the process issuing this command into a wait 
state until a specified batch job completes execution. 

WAIT 

Places the current process in a wait state until a 
specified period of time has elapsed. 

WRITE 

Writes a record to a specified output file. 


C—3 













Index 


A 


Access mode 

supervisor mode • 2-4 
user mode *2-4 
Ampersand (&) 

requesting symbol substitution *2-15 
Annotated command procedures* A-1 to A-29 
Apostrophe 

requesting symbol substitution *2-14 
APPEND qualifier (OPEN command) • 6-9 
ASSIGN command *2-2 
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Batch execution of command procedure* 1-6 
Batch job 

deleting (stopping) after submission *8-8 

providing input to • 8-4 

restarting • 8-9 

specifying a queue • 8-3 

stopping • 8-8 

submitting a command procedure as *8-1 
synchronizing multiple procedures *8-10 
uses of *8-1 
Batch job log file *8-5 
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CLOSE command *6-1 
Command 

continuing to a second line* 1-3 
in command procedures *C-1 to C-3 
Command level, definition* 1-7 
Comment character (!)• 1-3 
Condition code 

as symbol $SEVERITY*7-2 
as symbol $STATUS*7-1 
definition *7-1 

Continuation character (-)• 1-3 
CTRL/Y 

action taken during execution • 7-6 


CTRL/Y (cont'd.) 

default action for nested procedure • 7-9 
disabling *7-10 

interrupting a command procedure • 7-6 
with ON command *7-7 
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Data lines* 1-2 

in command procedures *3-5 
Data type 

DCL conversion rules *2-13 
DEASSIGN command *2-2 
DECK command *3-5 
DEFINE command *2-2 
DELETE /ENTRY command *8-8 
DELETE/SYMBOL command *2-9 
Dollar sign ($) 

including as data *3-5 
in command procedure* 1-2 
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EOD command *3-5 
Equal to operator 

symbol for in expressions *2-13 
Equivalence string 
definition *2-1 
Error condition 

determining severity level *7-2 
Error handling 

disabling CTRL/Y *7-6 
disabling error checking *7-5 
handling I/O errors *6-10 
specifying actions for different severity levels • 
7-4 

with ON command *7-4 
Errors 

locating with SET VERIFY *3-12 
Exclamation point (I) 

as a comment character* 1-3 
Execute Procedure (@) command* 1-5 
Execution of command procedure on remote 
node*1-6 
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EXIT command*5-16 


F 


F$CVSI lexical function* B-1 
F$CVTIME lexical function *B-1 
F$CVUI lexical function* B-1 
F$DIRECTORY lexical function* B-1 
F$EDIT lexical function *B-1 
F$ELEMENT lexical function • B-1 
with F$EXTRACT *4-9 
FSENVIRONMENT lexical function*B-1 
obtaining current default *4-3 
F$EXTRACT lexical function*B-1 
extracting a string • 4-9 
F$FAO lexical function*B-1 
defining record fields *4-11 
F$FILE—ATTRIBUTES lexical function*B-1 
F$GETDVI lexical function*B-1 
FSGETJPI lexical function*B-1 
F$GETQUI lexical function*B-1 
obtaining queue information • 4-5 
F$GETSYI lexical function *B-2 

obtaining system or cluster information • 4-5 
F$IDENTIFIER lexical function *B-2 
F$INTEGER lexical function *B-2 
converting data type *4-13 
evaluating data *4-13 
F$LENGTH lexical function • B-2 
with F$L0CATE*4-9 
FSLOCATE lexical function*B-2 
with F$LENGTH*4-9 
F$LOGICAL lexical function 

see F$TRNLAM lexical function 
F$MESSAGE lexical function*B-2 
F$MODE lexical function • B-2 
FSPARSE lexical function • B-2 
F$PID lexical function*B-2 

obtaining process identification • 4-5 
F$PRIVILEGE lexical function*B-2 
F$PROCESS lexical function • B-2 
F$SEARCH lexical function*B-2 

avoiding command procedure errors *4-7 
searching for a file *4-7 
F$SETPRV lexical function*B-2 
F$STRING lexical function • B-3 
converting data type *4-13 
F$TIME lexical function • B-3 


F$TRNLNM lexical function • B-3 
translating logical names *4-8 
F$TYPE lexical function • B-3 
F$USER lexical function*B-3 
FSVERIFY lexical function*B-3 
changing VERIFY state *3-13 
File type 

default* 1-2 
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GOSUB command *5-10 
GOTO command 
with labels *5-9 

with the IF...THEN language construct*5-10 
Greater than operator 

symbol for in expressions *2-13 
Greater than or equal to operator 
symbol for in expressions *2-13 


H 


Hyphen 

see Continuation character 
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IF command 

controlling execution flow *5-6 
evaluating input of INQUIRE command *5-8 
executing a block of commands after *5-8 
restrictions to the IF-THEN-ELSE construct*5-6 
syntax rules for *5-6 
testing severity level *7-2 
with GOTO command *5-10 
Input 

data lines* 1-2, 3-5 
entering from a terminal *3-6 
obtaining with INQUIRE command *3-4 
obtaining with READ command *3-4 
opening a file to accept *6-2 
passing as a parameter to a command 
procedure *3-1 
to an executable image *3-5 
to batch jobs • 8-4 
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INQUIRE command 

converting input data with*3-4 
evaluating input from using the IF command* 
5-8 

in a batch job command procedure *3-4 
obtaining input *3-4 

using to obtain a value for a variable *5-2 
Interactive execution of command procedure* 1-5 


L 


Label 

in command procedure* 1-4 
with the GOSUB command *5-10 
with the GOTO command *5-9 
Less than operator 

symbol for in expressions *2-13 
Less than or equal to operator 
symbol for in expressions*2-13 
Lexical functions *B-1 to B-3 
definition *2-11,4-1 
evaluating *2-11 
specifying arguments for *2-11 
summary of *B-1 
with WRITE command *6-5 
Log file 

contents of *8-5 

examining during execution of batch job *8-5 
status when batch job is stopped abnormally* 
8-8 

Logical names 

access modes of *2-4 
assigning *2-2 
attributes of *2-4 
creating • 2-2 
definition *2-1 
deleting *2-2 

differences from symbols *2-15 
displaying *2-4 
in a file specification • 2-2 
search list *2-4 
to obtain output value *3-12 
to refer to a device • 2-2 
translation of *2-1 
with the OPEN command *6-1 
Logical name table 
creating • 2-3 
definition • 2-3 
group table *2-3 
job table *2-3 


Logical name table (cont'd.) 
process table • 2-3 
system table • 2-3 
LOGIN.COM 

See Login command procedure 
Login command procedure* 1-9 
execution of for batch jobs • 8-2 
location of • 1-11 
personal* 1-9 
system-defined* 1-9 
Loop 

in a command procedure*5-14 
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Nested command procedure* 1-7 
default CTRL/Y action *7-9 
Not equal to operator 

symbol for in expressions *2-13 
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ON command 

for error handling • 7-4 
specifying severity level *7-4 
with CTRL/Y *7-7 
with severity level • 7-2 
OPEN command *6-1 

appending records to an existing file *6-9 
creating a new output file • 6-8 
opening a file for reading *6-2 
opening a file for writing *6-2 
opening a shareable file *6-3 
Operators 

in expressions *2-12 
rules for data types *2-13 
Output 

creating a new ouput file • 6-8 
default for batch job command procedures* 
3-8 

default for interactive command procedures* 
3-8 

directing in a command procedure *3-7 
redefining for interactive command procedures • 
3-8 

suppressing by redefining SYS$OUTPUT *3-8 
to a terminal *3-14 
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Parameters 

case value of strings *3-2 
null *3-2 

passing to a command procedure *3-1 
Process permanent files 

changing the default value of •2-7 
definition • 2-5 
SYS$COMMAND • 2-6 
SYS$ERROR • 2-6 
SYS$INPUT* 2-6 
SYS$OUTPUT•2-6 
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READ command *6-3 

case value of data obtained • 3-4 
using to obtain data • 3-4 
Reading a record • 6-3 
READ qualifier (OPEN command) *6-2 
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appending to a file • 6—9 
reading from a file • 6-2 
updating • 6-7 
writing to a file • 6-2 
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Search list 

definition • 2-4 
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SET CONTROL _Y command • 7-10 
SET ENTRY command *8-7 
SET NOON command*7-5 
SET QUEUE/ENTRY command *8-7 
SET SYMBOL command *2-8 
SET VERIFY command 

changing with F$VERIFY lexical function *3-13 
debugging command procedure with* 1-13 
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testing for successful (odd) value *7-2 
value with SET NOON *7-5 


Severity level 

determining *7-2 

specifying error handling based upon • 7-4 
testing for with IF command • 7-2 
use of ON command with *7-2 
Shareable files 
opening *6-3 

SHOW ENTRY command *8-6 
SHOW LOGICAL command *2-4 
SHOW QUEUE command *8-6 
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commands that do not set *7-2 
definition *7-1 
format of* 7-1 

severity of error condition • 7-2 
testing for successful (odd) value • 7-2 
value with SET NOON *7-5 
STOP command *5-16 
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comparing, using operators • 5-7 
SUBMIT command 

specifying multiple command procedures with* 
8-3 

with batch job command procedure* 1-6, 8-1 
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as variables *2-7 
creating *2-7 
definition • 2-7 
deleting • 2-9 
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evaluating using IF command *5-8 
global *2-7 
local *2-7 
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obtaining an output value with *3-11 
substitution *2-14 
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SYNCHRONIZE command *8-10 
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changing the default value of *2-7 
in batch job command procedure *2-6 
in interactive command procedure *2-6 
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3-6 

SYS$ERROR process permanent file *2-6 
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in batch job command procedure *2-6, 8-5 
in interactive command procedure • 2-6 
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changing the default value of *2-7 
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